signedly 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. signedly/__init__.py +92 -0
  2. signedly/api/__init__.py +14 -0
  3. signedly/api/api_request_logs_api.py +686 -0
  4. signedly/api/authentication_api.py +603 -0
  5. signedly/api/bulk_sending_api.py +858 -0
  6. signedly/api/documents_api.py +2465 -0
  7. signedly/api/downloads_api.py +840 -0
  8. signedly/api/fields_api.py +2308 -0
  9. signedly/api/sending_api.py +890 -0
  10. signedly/api/signatories_api.py +1165 -0
  11. signedly/api/templates_api.py +1452 -0
  12. signedly/api/webhooks_api.py +2582 -0
  13. signedly/api_client.py +798 -0
  14. signedly/api_response.py +21 -0
  15. signedly/configuration.py +596 -0
  16. signedly/exceptions.py +200 -0
  17. signedly/helpers.py +89 -0
  18. signedly/models/__init__.py +66 -0
  19. signedly/models/create_bulk_send202_response.py +105 -0
  20. signedly/models/create_bulk_send_request.py +101 -0
  21. signedly/models/create_document_fields_request_inner.py +156 -0
  22. signedly/models/create_document_from_template200_response.py +101 -0
  23. signedly/models/create_document_from_template_request.py +115 -0
  24. signedly/models/create_document_from_template_request_recipients_inner.py +92 -0
  25. signedly/models/create_signatories_request.py +100 -0
  26. signedly/models/create_signatories_request_signatories_inner.py +92 -0
  27. signedly/models/create_signatory_request.py +94 -0
  28. signedly/models/create_template_fields_request_inner.py +156 -0
  29. signedly/models/create_webhook_endpoint_request.py +103 -0
  30. signedly/models/delete_field_request.py +88 -0
  31. signedly/models/document.py +159 -0
  32. signedly/models/document_page.py +113 -0
  33. signedly/models/document_status_page.py +113 -0
  34. signedly/models/document_status_row.py +90 -0
  35. signedly/models/fill_and_send_document_request.py +116 -0
  36. signedly/models/fill_and_send_document_request_elements_inner.py +96 -0
  37. signedly/models/get_access_token_request.py +90 -0
  38. signedly/models/get_audit_trail_link200_response.py +88 -0
  39. signedly/models/get_download_status200_response.py +90 -0
  40. signedly/models/list_bulk_send_columns200_response_inner.py +92 -0
  41. signedly/models/model_field.py +202 -0
  42. signedly/models/page.py +102 -0
  43. signedly/models/refresh_access_token200_response.py +99 -0
  44. signedly/models/refresh_access_token_request.py +88 -0
  45. signedly/models/request_count_page.py +113 -0
  46. signedly/models/request_hit.py +93 -0
  47. signedly/models/request_log.py +108 -0
  48. signedly/models/request_log_page.py +113 -0
  49. signedly/models/send_document200_response.py +88 -0
  50. signedly/models/send_document_by_link200_response.py +90 -0
  51. signedly/models/send_document_by_link_request.py +91 -0
  52. signedly/models/send_document_request.py +102 -0
  53. signedly/models/signatory.py +119 -0
  54. signedly/models/template.py +124 -0
  55. signedly/models/template_field.py +202 -0
  56. signedly/models/template_page.py +113 -0
  57. signedly/models/update_document_field_by_body_request.py +158 -0
  58. signedly/models/update_document_field_by_body_request_items_inner.py +92 -0
  59. signedly/models/update_webhook_endpoint_request.py +105 -0
  60. signedly/models/upload.py +110 -0
  61. signedly/models/upload_document_for_one_signer200_response.py +90 -0
  62. signedly/models/upload_document_for_one_signer_request.py +96 -0
  63. signedly/models/upload_document_request.py +101 -0
  64. signedly/models/webhook_delivery.py +140 -0
  65. signedly/models/webhook_delivery_page.py +113 -0
  66. signedly/models/webhook_endpoint.py +116 -0
  67. signedly/models/webhook_endpoint_with_secret.py +120 -0
  68. signedly/py.typed +0 -0
  69. signedly/rest.py +258 -0
  70. signedly-0.1.0.dist-info/LICENSE +21 -0
  71. signedly-0.1.0.dist-info/METADATA +18 -0
  72. signedly-0.1.0.dist-info/RECORD +74 -0
  73. signedly-0.1.0.dist-info/WHEEL +5 -0
  74. signedly-0.1.0.dist-info/top_level.txt +1 -0
signedly/exceptions.py ADDED
@@ -0,0 +1,200 @@
1
+ # coding: utf-8
2
+
3
+ """
4
+ Signedly API
5
+
6
+ The Signedly REST API lets your system upload documents, add signatories and fields, send them for signing and download the signed result. Every path starts with `/ap1/`, and every request and response body is JSON unless an endpoint says otherwise (the uploads are `multipart/form-data`). ## Authentication 1. In the Signedly web app, open **Account & Settings → API** and generate a **client ID** and **client secret** for your organisation. 2. `POST /ap1/token/` with them. You get an `access_token` (valid **2 hours**) and a `refresh_token` (valid **7 days**). While both are still valid, calling `/ap1/token/` again returns the same pair. 3. Send the access token on every other call: `Authorization: Bearer <access_token>`. 4. When the access token expires, `POST /ap1/refreshtoken/` with the refresh token for a new access token. When the refresh token has expired too, call `/ap1/token/` again. `/ap1/token/` and `/ap1/refreshtoken/` allow 60 calls a minute per IP address; more answer 429. A missing, unknown or expired access token answers 403 (`\"Client not found\"` or `\"Access token expired\"`). The API acts for your **organisation's admin account**: documents you upload belong to it and appear in its Signedly web app, and you can reach only that account's documents, templates, signatories and fields. Another organisation's IDs answer 404, as if they didn't exist. ## Plans What the API allows depends on the Signedly plan of your **organisation's admin account** (Account & Settings → Account & Plan). The same rules apply to live and test keys. | What | Free | Personal Pro | Business Pro | Teams | |---|---|---|---|---| | Generate live and test keys (Account & Settings → API) | – | ✓ | ✓ | ✓ | | Every endpoint, `/ap1/token/` and `/ap1/refreshtoken/` included | – | ✓ | ✓ | ✓ | | `require_email_otp` on `POST /ap1/signatories/` and `POST /ap1/signatories/bulk/` | – | ✓ | ✓ | ✓ | | Bulk send: `GET /ap1/bulk-sends/columns/` and `POST /ap1/bulk-sends/` | – | – | – | ✓ | The API is part of the paid plans. On Free (or with no plan) every call answers 403 `\"... Your plan doesn't include API access.\"`, with live or test keys, also with a token or keys made earlier; they work again once the plan is paid. On a paid plan, a feature it doesn't include answers 400 with `\"Your plan doesn't include ...\"` and changes nothing, and `GET /ap1/bulk-sends/{id}/` still reports bulk sends already made. Live documents also need an API contract with Signedly. Without one, or with an unpaid API invoice, `POST /ap1/upload/` (except templates), `/ap1/upload_app/`, `/ap1/documents/fromtemplate/` and `/ap1/bulk-sends/` answer 402 with live keys. Test keys work without a contract (see Sandbox). ## Sending a document for signing 1. `POST /ap1/upload/` a PDF or DOCX (`type` 2). The document is prepared in the background: find it in `GET /ap1/documents/?name=<name>` (its `upload.id` is the upload's `id`), and wait until `GET /ap1/documents/{id}/pages/` lists its pages. 2. `POST /ap1/signatories/` (one) or `POST /ap1/signatories/bulk/` (several) to add the people who sign. 3. `POST /ap1/documents/fields/` to place the fields each signatory fills in. 4. Send it: - `POST /ap1/document/send/` emails every signatory a signing link (with ordered signing, only the first; each next one is emailed in turn), or - `POST /ap1/document/send_url/` sends no email and returns the first signatory's signing link, for you to show or send yourself. 5. Poll `GET /ap1/documents-status-list/` (or `GET /ap1/documents/`) until the status is 6 (Completed), then `GET /ap1/document/download-link/` for the signed PDF and `GET /ap1/document/download-audit-link/` for its audit trail. **From a template:** upload with `type` 4 and a `template_name` (or make the template in the web app), place its fields with `POST /ap1/templates/fields/`, then for each signing make a document with `POST /ap1/documents/fromtemplate/`, add its signatory, and send it. **One signer, one call:** `POST /ap1/upload_app/` uploads a PDF or DOCX for one signer and returns their signing link in `redirect_url`; the signer places their own signature. After signing they go to the `redirect_url` you sent, and the signed PDF and its audit trail are emailed to `final_email` (otherwise to your organisation's admin). ## Quick start with curl Each step uses an ID from the step before. `$API` is this server, e.g. `https://l0ads.signedly.com`. ```bash # 1. Token curl -X POST $API/ap1/token/ -H 'Content-Type: application/json' \\ -d '{\"client_id\": \"<client id>\", \"client_secret\": \"<client secret>\"}' TOKEN=<access_token from the answer> # 2. Upload a PDF (answers with the upload's id) curl -X POST $API/ap1/upload/ -H \"Authorization: Bearer $TOKEN\" \\ -F file=@nda.pdf -F name=nda-ann-lee -F type=2 # 3. Find the document, then wait until it has pages curl \"$API/ap1/documents/?name=nda-ann-lee\" -H \"Authorization: Bearer $TOKEN\" DOC=<results[0].id> curl $API/ap1/documents/$DOC/pages/ -H \"Authorization: Bearer $TOKEN\" PAGE=<[0].id> # 4. Add the signatory curl -X POST $API/ap1/signatories/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"name\": \"Ann Lee\", \"email\": \"ann@example.com\"}' SIGNER=<id from the answer> # 5. Place her signature: 150 × 40 points, 72 points from the left, 640 from the top curl -X POST $API/ap1/documents/fields/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '[{\"document_id\": \"'$DOC'\", \"signatory_id\": \"'$SIGNER'\", \"kind\": 2, \"label\": \"Signature\", \"placeholder\": \"Sign here\", \"page\": \"'$PAGE'\", \"page_number\": 0, \"x\": 72, \"y\": 640, \"width\": 150, \"height\": 40}]' # 6. Send it (Ann gets the signing email) curl -X POST $API/ap1/document/send/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"subject\": \"Please sign the NDA\", \"message\": \"Hi Ann, please sign by Friday.\", \"expiry_date\": \"2026-12-31\"}' # 7. Poll until status is 6 (Completed), then get the signed PDF curl \"$API/ap1/documents-status-list/?document_ids=$DOC\" -H \"Authorization: Bearer $TOKEN\" curl \"$API/ap1/document/download-link/?id=$DOC\" -H \"Authorization: Bearer $TOKEN\" ``` ## Postman Import the whole API into Postman with **Import → Link** and `<this server>/swaggerap1/postman.json`. Set `client_id` and `client_secret` in the collection's **Variables**, run **Get an access token** (it saves the token for every other request), and set `document_id` when a request needs one. ## Webhooks Instead of polling, add an endpoint with `POST /ap1/webhooks/` (or in **Account & Settings → API**) and Signedly posts your organisation's document events to it: `document.sent`, `document.viewed`, `document.signed`, `document.approved`, `document.completed`, `document.rejected` and `document.expired` (all of them, or the `events` you choose). Each is a JSON `POST`: ```json {\"id\": \"5b7f…\", \"type\": \"document.signed\", \"created_at\": \"2026-10-27T09:12:00+00:00\", \"test\": false, \"data\": {\"document\": {\"id\": \"6f0c…\", \"name\": \"nda.pdf\", \"status\": 5}, \"recipient\": {\"id\": \"0b6e…\", \"email\": \"ann@example.com\", \"name\": \"Ann Lee\", \"role\": \"signer\"}}} ``` `recipient` is null for events no recipient caused (sent, completed, expired); `test` is true for documents made with your test keys. Fetch anything else, such as download links, with your access token: events never carry links. **Check every event is from Signedly.** The `Signedly-Signature` header is `t=<unix seconds>,v1=<signature>`, where the signature is the hex HMAC-SHA256 of `<t>.<raw body>` with the endpoint's secret. Refuse an event whose signature doesn't match or whose `t` is more than 5 minutes off: ```python import hashlib, hmac, time def is_from_signedly(secret, header, raw_body): parts = dict(item.split(\"=\", 1) for item in header.split(\",\")) signed = f\"{parts['t']}.{raw_body.decode()}\".encode() expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() fresh = abs(time.time() - int(parts[\"t\"])) <= 300 return fresh and hmac.compare_digest(parts[\"v1\"], expected) ``` **Answer 2xx within 10 seconds**, then do the work. Anything else is retried after 1 and 5 minutes, then 30 minutes and 2, 5 and 10 hours (7 tries in about 18 hours). `Signedly-Event-Id` is the same on every try of an event: use it to ignore repeats. After 20 events in a row fail for good, Signedly switches the endpoint off and emails your organisation's admin; switch it on again with `PUT /ap1/webhooks/{id}/` and `\"is_active\": true`. Each endpoint's deliveries and their last answers are at `GET /ap1/webhooks/{id}/deliveries/`, and any can be sent again. ## Sandbox Build and test against the API without paying for documents: in **Account & Settings → API**, generate your **test keys**, and get a token with them at `/ap1/token/` as usual. Everything works the same, except that what you upload or make from a template with a test token is a **test document** (`is_test` on its upload): - every page of its PDF and of its audit trail says **TEST – NOT LEGALLY BINDING**; - its emails are real, with `[TEST]` at the start of the subject; - it isn't billed or counted toward your plan; - your organisation can make 50 a calendar month (templates don't count); the next upload answers 429. ## Fields Positions and sizes are in **PDF points** (1/72 inch), measured from the **top-left corner** of the page as it is displayed (rotation applied). `page_number` counts pages from 0. A field must sit wholly on its page (1 point of tolerance); otherwise it is refused with 400. A field's page and signatory can't be changed later: delete the field and add it again. ## Status values **Document `status`:** 1 Draft · 2 Signees Added · 3 Prepared · 4 Sent · 5 In Progress · 6 Completed · 7 Rejected · 8 Archived · 9 Expired. Signatories, fields and sends are only accepted while a document is 1–3 (not yet sent). **Signatory `status`:** 1 Waiting · 2 Invited · 3 Signed · 4 Viewed · 5 Rejected. ## Lists `GET /ap1/documents/`, `/ap1/documents-status-list/`, `/ap1/templates/`, `/ap1/logs/` and `/ap1/logs/hits/` are paged: pass `limit` (default 10) and `offset`, and read `count`, `next`, `previous` and `results` from the response. ## Errors | Status | Meaning | |---|---| | 400 | The request was refused, also when your plan doesn't include it (see Plans); the body says why (`{\"error\": \"...\"}`, or the name of each bad field with its messages). Nothing was changed. | | 403 | The access token is missing, unknown or expired; the client ID and secret or the refresh token were refused; the organisation's plan has no API access (Free, see Plans); or an `expiry_date` isn't in the future (`\"Invalid Date Entered\"`). | | 402 | No API contract, or an unpaid API invoice: live documents are refused (test keys keep working). | | 404 | The document, template, signatory or field doesn't exist or isn't yours. | | 429 | Too many token requests (wait a minute), or this month's 50 test documents are used. | | 5xx | Our side failed; retry later. | A send that times out may still have worked: check the document's status before sending again (a second send of a sent document answers 400). Download, view and audit links are valid for about 7 days; ask for a new one whenever you need it.
7
+
8
+ The version of the OpenAPI document: v1
9
+ Contact: info@signedly.com
10
+ Generated by OpenAPI Generator (https://openapi-generator.tech)
11
+
12
+ Do not edit the class manually.
13
+ """ # noqa: E501
14
+
15
+ from typing import Any, Optional
16
+ from typing_extensions import Self
17
+
18
+ class OpenApiException(Exception):
19
+ """The base exception class for all OpenAPIExceptions"""
20
+
21
+
22
+ class ApiTypeError(OpenApiException, TypeError):
23
+ def __init__(self, msg, path_to_item=None, valid_classes=None,
24
+ key_type=None) -> None:
25
+ """ Raises an exception for TypeErrors
26
+
27
+ Args:
28
+ msg (str): the exception message
29
+
30
+ Keyword Args:
31
+ path_to_item (list): a list of keys an indices to get to the
32
+ current_item
33
+ None if unset
34
+ valid_classes (tuple): the primitive classes that current item
35
+ should be an instance of
36
+ None if unset
37
+ key_type (bool): False if our value is a value in a dict
38
+ True if it is a key in a dict
39
+ False if our item is an item in a list
40
+ None if unset
41
+ """
42
+ self.path_to_item = path_to_item
43
+ self.valid_classes = valid_classes
44
+ self.key_type = key_type
45
+ full_msg = msg
46
+ if path_to_item:
47
+ full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
48
+ super(ApiTypeError, self).__init__(full_msg)
49
+
50
+
51
+ class ApiValueError(OpenApiException, ValueError):
52
+ def __init__(self, msg, path_to_item=None) -> None:
53
+ """
54
+ Args:
55
+ msg (str): the exception message
56
+
57
+ Keyword Args:
58
+ path_to_item (list) the path to the exception in the
59
+ received_data dict. None if unset
60
+ """
61
+
62
+ self.path_to_item = path_to_item
63
+ full_msg = msg
64
+ if path_to_item:
65
+ full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
66
+ super(ApiValueError, self).__init__(full_msg)
67
+
68
+
69
+ class ApiAttributeError(OpenApiException, AttributeError):
70
+ def __init__(self, msg, path_to_item=None) -> None:
71
+ """
72
+ Raised when an attribute reference or assignment fails.
73
+
74
+ Args:
75
+ msg (str): the exception message
76
+
77
+ Keyword Args:
78
+ path_to_item (None/list) the path to the exception in the
79
+ received_data dict
80
+ """
81
+ self.path_to_item = path_to_item
82
+ full_msg = msg
83
+ if path_to_item:
84
+ full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
85
+ super(ApiAttributeError, self).__init__(full_msg)
86
+
87
+
88
+ class ApiKeyError(OpenApiException, KeyError):
89
+ def __init__(self, msg, path_to_item=None) -> None:
90
+ """
91
+ Args:
92
+ msg (str): the exception message
93
+
94
+ Keyword Args:
95
+ path_to_item (None/list) the path to the exception in the
96
+ received_data dict
97
+ """
98
+ self.path_to_item = path_to_item
99
+ full_msg = msg
100
+ if path_to_item:
101
+ full_msg = "{0} at {1}".format(msg, render_path(path_to_item))
102
+ super(ApiKeyError, self).__init__(full_msg)
103
+
104
+
105
+ class ApiException(OpenApiException):
106
+
107
+ def __init__(
108
+ self,
109
+ status=None,
110
+ reason=None,
111
+ http_resp=None,
112
+ *,
113
+ body: Optional[str] = None,
114
+ data: Optional[Any] = None,
115
+ ) -> None:
116
+ self.status = status
117
+ self.reason = reason
118
+ self.body = body
119
+ self.data = data
120
+ self.headers = None
121
+
122
+ if http_resp:
123
+ if self.status is None:
124
+ self.status = http_resp.status
125
+ if self.reason is None:
126
+ self.reason = http_resp.reason
127
+ if self.body is None:
128
+ try:
129
+ self.body = http_resp.data.decode('utf-8')
130
+ except Exception:
131
+ pass
132
+ self.headers = http_resp.getheaders()
133
+
134
+ @classmethod
135
+ def from_response(
136
+ cls,
137
+ *,
138
+ http_resp,
139
+ body: Optional[str],
140
+ data: Optional[Any],
141
+ ) -> Self:
142
+ if http_resp.status == 400:
143
+ raise BadRequestException(http_resp=http_resp, body=body, data=data)
144
+
145
+ if http_resp.status == 401:
146
+ raise UnauthorizedException(http_resp=http_resp, body=body, data=data)
147
+
148
+ if http_resp.status == 403:
149
+ raise ForbiddenException(http_resp=http_resp, body=body, data=data)
150
+
151
+ if http_resp.status == 404:
152
+ raise NotFoundException(http_resp=http_resp, body=body, data=data)
153
+
154
+ if 500 <= http_resp.status <= 599:
155
+ raise ServiceException(http_resp=http_resp, body=body, data=data)
156
+ raise ApiException(http_resp=http_resp, body=body, data=data)
157
+
158
+ def __str__(self):
159
+ """Custom error messages for exception"""
160
+ error_message = "({0})\n"\
161
+ "Reason: {1}\n".format(self.status, self.reason)
162
+ if self.headers:
163
+ error_message += "HTTP response headers: {0}\n".format(
164
+ self.headers)
165
+
166
+ if self.data or self.body:
167
+ error_message += "HTTP response body: {0}\n".format(self.data or self.body)
168
+
169
+ return error_message
170
+
171
+
172
+ class BadRequestException(ApiException):
173
+ pass
174
+
175
+
176
+ class NotFoundException(ApiException):
177
+ pass
178
+
179
+
180
+ class UnauthorizedException(ApiException):
181
+ pass
182
+
183
+
184
+ class ForbiddenException(ApiException):
185
+ pass
186
+
187
+
188
+ class ServiceException(ApiException):
189
+ pass
190
+
191
+
192
+ def render_path(path_to_item):
193
+ """Returns a string representation of a path"""
194
+ result = ""
195
+ for pth in path_to_item:
196
+ if isinstance(pth, int):
197
+ result += "[{0}]".format(pth)
198
+ else:
199
+ result += "['{0}']".format(pth)
200
+ return result
signedly/helpers.py ADDED
@@ -0,0 +1,89 @@
1
+ """Hand-written helpers, kept when the SDK is regenerated (.openapi-generator-ignore).
2
+
3
+ from signedly.helpers import SignedlyClient, verify_webhook_signature
4
+ from signedly.api.documents_api import DocumentsApi
5
+
6
+ client = SignedlyClient(CLIENT_ID, CLIENT_SECRET) # test keys work the same
7
+ documents = DocumentsApi(client.api_client).list_documents()
8
+
9
+ The access token is fetched on the first call and renewed (refresh token, then
10
+ the keys again) shortly before it expires.
11
+ """
12
+
13
+ import hashlib
14
+ import hmac
15
+ import threading
16
+ import time
17
+ from datetime import datetime, timezone
18
+
19
+ from signedly.api.authentication_api import AuthenticationApi
20
+ from signedly.api_client import ApiClient
21
+ from signedly.configuration import Configuration
22
+ from signedly.models.get_access_token_request import GetAccessTokenRequest
23
+ from signedly.models.refresh_access_token_request import RefreshAccessTokenRequest
24
+
25
+ LIVE_HOST = "https://l0ads.signedly.com"
26
+ RENEW_BEFORE = 120 # seconds before expiry
27
+ SIGNATURE_TOLERANCE = 300 # seconds
28
+
29
+
30
+ def _seconds(moment):
31
+ if moment is None:
32
+ return 0
33
+ if moment.tzinfo is None:
34
+ moment = moment.replace(tzinfo=timezone.utc)
35
+ return moment.timestamp()
36
+
37
+
38
+ class SignedlyClient:
39
+ """An ApiClient that logs in with the client ID and secret and keeps the
40
+ access token fresh. Pass `api_client` to any generated API class."""
41
+
42
+ def __init__(self, client_id, client_secret, host=LIVE_HOST):
43
+ self.client_id, self.client_secret = client_id, client_secret
44
+ self.configuration = Configuration(host=host)
45
+ self.configuration.refresh_api_key_hook = self._ensure_token
46
+ self.api_client = ApiClient(self.configuration)
47
+ self._auth = AuthenticationApi(ApiClient(Configuration(host=host)))
48
+ self._lock = threading.Lock()
49
+ self._expires = self._refresh_expires = 0
50
+ self._refresh_token = None
51
+
52
+ def _ensure_token(self, configuration):
53
+ with self._lock:
54
+ now = time.time()
55
+ if now < self._expires - RENEW_BEFORE:
56
+ return
57
+ if self._refresh_token and now < self._refresh_expires - RENEW_BEFORE:
58
+ token = self._auth.refresh_access_token(
59
+ RefreshAccessTokenRequest(refresh_token=self._refresh_token)
60
+ )
61
+ else:
62
+ token = self._auth.get_access_token(
63
+ GetAccessTokenRequest(
64
+ client_id=self.client_id, client_secret=self.client_secret
65
+ )
66
+ )
67
+ self._refresh_token = token.refresh_token or self._refresh_token
68
+ self._expires = _seconds(token.expiry_date)
69
+ if token.refresh_token_expiry_date:
70
+ self._refresh_expires = _seconds(token.refresh_token_expiry_date)
71
+ configuration.api_key["Bearer"] = token.access_token
72
+ configuration.api_key_prefix["Bearer"] = "Bearer"
73
+
74
+
75
+ def verify_webhook_signature(secret, signature_header, raw_body, now=None):
76
+ """True if `Signedly-Signature` signs this raw body with the endpoint's secret
77
+ and was made within 5 minutes. Pass the body exactly as received (bytes)."""
78
+ try:
79
+ parts = dict(item.split("=", 1) for item in signature_header.split(","))
80
+ timestamp = int(parts["t"])
81
+ except (KeyError, ValueError, AttributeError):
82
+ return False
83
+ if abs((time.time() if now is None else now) - timestamp) > SIGNATURE_TOLERANCE:
84
+ return False
85
+ body = raw_body.decode() if isinstance(raw_body, bytes) else raw_body
86
+ expected = hmac.new(
87
+ secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256
88
+ ).hexdigest()
89
+ return hmac.compare_digest(parts.get("v1", ""), expected)
@@ -0,0 +1,66 @@
1
+ # coding: utf-8
2
+
3
+ # flake8: noqa
4
+ """
5
+ Signedly API
6
+
7
+ The Signedly REST API lets your system upload documents, add signatories and fields, send them for signing and download the signed result. Every path starts with `/ap1/`, and every request and response body is JSON unless an endpoint says otherwise (the uploads are `multipart/form-data`). ## Authentication 1. In the Signedly web app, open **Account & Settings → API** and generate a **client ID** and **client secret** for your organisation. 2. `POST /ap1/token/` with them. You get an `access_token` (valid **2 hours**) and a `refresh_token` (valid **7 days**). While both are still valid, calling `/ap1/token/` again returns the same pair. 3. Send the access token on every other call: `Authorization: Bearer <access_token>`. 4. When the access token expires, `POST /ap1/refreshtoken/` with the refresh token for a new access token. When the refresh token has expired too, call `/ap1/token/` again. `/ap1/token/` and `/ap1/refreshtoken/` allow 60 calls a minute per IP address; more answer 429. A missing, unknown or expired access token answers 403 (`\"Client not found\"` or `\"Access token expired\"`). The API acts for your **organisation's admin account**: documents you upload belong to it and appear in its Signedly web app, and you can reach only that account's documents, templates, signatories and fields. Another organisation's IDs answer 404, as if they didn't exist. ## Plans What the API allows depends on the Signedly plan of your **organisation's admin account** (Account & Settings → Account & Plan). The same rules apply to live and test keys. | What | Free | Personal Pro | Business Pro | Teams | |---|---|---|---|---| | Generate live and test keys (Account & Settings → API) | – | ✓ | ✓ | ✓ | | Every endpoint, `/ap1/token/` and `/ap1/refreshtoken/` included | – | ✓ | ✓ | ✓ | | `require_email_otp` on `POST /ap1/signatories/` and `POST /ap1/signatories/bulk/` | – | ✓ | ✓ | ✓ | | Bulk send: `GET /ap1/bulk-sends/columns/` and `POST /ap1/bulk-sends/` | – | – | – | ✓ | The API is part of the paid plans. On Free (or with no plan) every call answers 403 `\"... Your plan doesn't include API access.\"`, with live or test keys, also with a token or keys made earlier; they work again once the plan is paid. On a paid plan, a feature it doesn't include answers 400 with `\"Your plan doesn't include ...\"` and changes nothing, and `GET /ap1/bulk-sends/{id}/` still reports bulk sends already made. Live documents also need an API contract with Signedly. Without one, or with an unpaid API invoice, `POST /ap1/upload/` (except templates), `/ap1/upload_app/`, `/ap1/documents/fromtemplate/` and `/ap1/bulk-sends/` answer 402 with live keys. Test keys work without a contract (see Sandbox). ## Sending a document for signing 1. `POST /ap1/upload/` a PDF or DOCX (`type` 2). The document is prepared in the background: find it in `GET /ap1/documents/?name=<name>` (its `upload.id` is the upload's `id`), and wait until `GET /ap1/documents/{id}/pages/` lists its pages. 2. `POST /ap1/signatories/` (one) or `POST /ap1/signatories/bulk/` (several) to add the people who sign. 3. `POST /ap1/documents/fields/` to place the fields each signatory fills in. 4. Send it: - `POST /ap1/document/send/` emails every signatory a signing link (with ordered signing, only the first; each next one is emailed in turn), or - `POST /ap1/document/send_url/` sends no email and returns the first signatory's signing link, for you to show or send yourself. 5. Poll `GET /ap1/documents-status-list/` (or `GET /ap1/documents/`) until the status is 6 (Completed), then `GET /ap1/document/download-link/` for the signed PDF and `GET /ap1/document/download-audit-link/` for its audit trail. **From a template:** upload with `type` 4 and a `template_name` (or make the template in the web app), place its fields with `POST /ap1/templates/fields/`, then for each signing make a document with `POST /ap1/documents/fromtemplate/`, add its signatory, and send it. **One signer, one call:** `POST /ap1/upload_app/` uploads a PDF or DOCX for one signer and returns their signing link in `redirect_url`; the signer places their own signature. After signing they go to the `redirect_url` you sent, and the signed PDF and its audit trail are emailed to `final_email` (otherwise to your organisation's admin). ## Quick start with curl Each step uses an ID from the step before. `$API` is this server, e.g. `https://l0ads.signedly.com`. ```bash # 1. Token curl -X POST $API/ap1/token/ -H 'Content-Type: application/json' \\ -d '{\"client_id\": \"<client id>\", \"client_secret\": \"<client secret>\"}' TOKEN=<access_token from the answer> # 2. Upload a PDF (answers with the upload's id) curl -X POST $API/ap1/upload/ -H \"Authorization: Bearer $TOKEN\" \\ -F file=@nda.pdf -F name=nda-ann-lee -F type=2 # 3. Find the document, then wait until it has pages curl \"$API/ap1/documents/?name=nda-ann-lee\" -H \"Authorization: Bearer $TOKEN\" DOC=<results[0].id> curl $API/ap1/documents/$DOC/pages/ -H \"Authorization: Bearer $TOKEN\" PAGE=<[0].id> # 4. Add the signatory curl -X POST $API/ap1/signatories/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"name\": \"Ann Lee\", \"email\": \"ann@example.com\"}' SIGNER=<id from the answer> # 5. Place her signature: 150 × 40 points, 72 points from the left, 640 from the top curl -X POST $API/ap1/documents/fields/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '[{\"document_id\": \"'$DOC'\", \"signatory_id\": \"'$SIGNER'\", \"kind\": 2, \"label\": \"Signature\", \"placeholder\": \"Sign here\", \"page\": \"'$PAGE'\", \"page_number\": 0, \"x\": 72, \"y\": 640, \"width\": 150, \"height\": 40}]' # 6. Send it (Ann gets the signing email) curl -X POST $API/ap1/document/send/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"subject\": \"Please sign the NDA\", \"message\": \"Hi Ann, please sign by Friday.\", \"expiry_date\": \"2026-12-31\"}' # 7. Poll until status is 6 (Completed), then get the signed PDF curl \"$API/ap1/documents-status-list/?document_ids=$DOC\" -H \"Authorization: Bearer $TOKEN\" curl \"$API/ap1/document/download-link/?id=$DOC\" -H \"Authorization: Bearer $TOKEN\" ``` ## Postman Import the whole API into Postman with **Import → Link** and `<this server>/swaggerap1/postman.json`. Set `client_id` and `client_secret` in the collection's **Variables**, run **Get an access token** (it saves the token for every other request), and set `document_id` when a request needs one. ## Webhooks Instead of polling, add an endpoint with `POST /ap1/webhooks/` (or in **Account & Settings → API**) and Signedly posts your organisation's document events to it: `document.sent`, `document.viewed`, `document.signed`, `document.approved`, `document.completed`, `document.rejected` and `document.expired` (all of them, or the `events` you choose). Each is a JSON `POST`: ```json {\"id\": \"5b7f…\", \"type\": \"document.signed\", \"created_at\": \"2026-10-27T09:12:00+00:00\", \"test\": false, \"data\": {\"document\": {\"id\": \"6f0c…\", \"name\": \"nda.pdf\", \"status\": 5}, \"recipient\": {\"id\": \"0b6e…\", \"email\": \"ann@example.com\", \"name\": \"Ann Lee\", \"role\": \"signer\"}}} ``` `recipient` is null for events no recipient caused (sent, completed, expired); `test` is true for documents made with your test keys. Fetch anything else, such as download links, with your access token: events never carry links. **Check every event is from Signedly.** The `Signedly-Signature` header is `t=<unix seconds>,v1=<signature>`, where the signature is the hex HMAC-SHA256 of `<t>.<raw body>` with the endpoint's secret. Refuse an event whose signature doesn't match or whose `t` is more than 5 minutes off: ```python import hashlib, hmac, time def is_from_signedly(secret, header, raw_body): parts = dict(item.split(\"=\", 1) for item in header.split(\",\")) signed = f\"{parts['t']}.{raw_body.decode()}\".encode() expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() fresh = abs(time.time() - int(parts[\"t\"])) <= 300 return fresh and hmac.compare_digest(parts[\"v1\"], expected) ``` **Answer 2xx within 10 seconds**, then do the work. Anything else is retried after 1 and 5 minutes, then 30 minutes and 2, 5 and 10 hours (7 tries in about 18 hours). `Signedly-Event-Id` is the same on every try of an event: use it to ignore repeats. After 20 events in a row fail for good, Signedly switches the endpoint off and emails your organisation's admin; switch it on again with `PUT /ap1/webhooks/{id}/` and `\"is_active\": true`. Each endpoint's deliveries and their last answers are at `GET /ap1/webhooks/{id}/deliveries/`, and any can be sent again. ## Sandbox Build and test against the API without paying for documents: in **Account & Settings → API**, generate your **test keys**, and get a token with them at `/ap1/token/` as usual. Everything works the same, except that what you upload or make from a template with a test token is a **test document** (`is_test` on its upload): - every page of its PDF and of its audit trail says **TEST – NOT LEGALLY BINDING**; - its emails are real, with `[TEST]` at the start of the subject; - it isn't billed or counted toward your plan; - your organisation can make 50 a calendar month (templates don't count); the next upload answers 429. ## Fields Positions and sizes are in **PDF points** (1/72 inch), measured from the **top-left corner** of the page as it is displayed (rotation applied). `page_number` counts pages from 0. A field must sit wholly on its page (1 point of tolerance); otherwise it is refused with 400. A field's page and signatory can't be changed later: delete the field and add it again. ## Status values **Document `status`:** 1 Draft · 2 Signees Added · 3 Prepared · 4 Sent · 5 In Progress · 6 Completed · 7 Rejected · 8 Archived · 9 Expired. Signatories, fields and sends are only accepted while a document is 1–3 (not yet sent). **Signatory `status`:** 1 Waiting · 2 Invited · 3 Signed · 4 Viewed · 5 Rejected. ## Lists `GET /ap1/documents/`, `/ap1/documents-status-list/`, `/ap1/templates/`, `/ap1/logs/` and `/ap1/logs/hits/` are paged: pass `limit` (default 10) and `offset`, and read `count`, `next`, `previous` and `results` from the response. ## Errors | Status | Meaning | |---|---| | 400 | The request was refused, also when your plan doesn't include it (see Plans); the body says why (`{\"error\": \"...\"}`, or the name of each bad field with its messages). Nothing was changed. | | 403 | The access token is missing, unknown or expired; the client ID and secret or the refresh token were refused; the organisation's plan has no API access (Free, see Plans); or an `expiry_date` isn't in the future (`\"Invalid Date Entered\"`). | | 402 | No API contract, or an unpaid API invoice: live documents are refused (test keys keep working). | | 404 | The document, template, signatory or field doesn't exist or isn't yours. | | 429 | Too many token requests (wait a minute), or this month's 50 test documents are used. | | 5xx | Our side failed; retry later. | A send that times out may still have worked: check the document's status before sending again (a second send of a sent document answers 400). Download, view and audit links are valid for about 7 days; ask for a new one whenever you need it.
8
+
9
+ The version of the OpenAPI document: v1
10
+ Contact: info@signedly.com
11
+ Generated by OpenAPI Generator (https://openapi-generator.tech)
12
+
13
+ Do not edit the class manually.
14
+ """ # noqa: E501
15
+
16
+
17
+ # import models into model package
18
+ from signedly.models.create_bulk_send202_response import CreateBulkSend202Response
19
+ from signedly.models.create_bulk_send_request import CreateBulkSendRequest
20
+ from signedly.models.create_document_fields_request_inner import CreateDocumentFieldsRequestInner
21
+ from signedly.models.create_document_from_template200_response import CreateDocumentFromTemplate200Response
22
+ from signedly.models.create_document_from_template_request import CreateDocumentFromTemplateRequest
23
+ from signedly.models.create_document_from_template_request_recipients_inner import CreateDocumentFromTemplateRequestRecipientsInner
24
+ from signedly.models.create_signatories_request import CreateSignatoriesRequest
25
+ from signedly.models.create_signatories_request_signatories_inner import CreateSignatoriesRequestSignatoriesInner
26
+ from signedly.models.create_signatory_request import CreateSignatoryRequest
27
+ from signedly.models.create_template_fields_request_inner import CreateTemplateFieldsRequestInner
28
+ from signedly.models.create_webhook_endpoint_request import CreateWebhookEndpointRequest
29
+ from signedly.models.delete_field_request import DeleteFieldRequest
30
+ from signedly.models.document import Document
31
+ from signedly.models.document_page import DocumentPage
32
+ from signedly.models.document_status_page import DocumentStatusPage
33
+ from signedly.models.document_status_row import DocumentStatusRow
34
+ from signedly.models.fill_and_send_document_request import FillAndSendDocumentRequest
35
+ from signedly.models.fill_and_send_document_request_elements_inner import FillAndSendDocumentRequestElementsInner
36
+ from signedly.models.get_access_token_request import GetAccessTokenRequest
37
+ from signedly.models.get_audit_trail_link200_response import GetAuditTrailLink200Response
38
+ from signedly.models.get_download_status200_response import GetDownloadStatus200Response
39
+ from signedly.models.list_bulk_send_columns200_response_inner import ListBulkSendColumns200ResponseInner
40
+ from signedly.models.model_field import ModelField
41
+ from signedly.models.page import Page
42
+ from signedly.models.refresh_access_token200_response import RefreshAccessToken200Response
43
+ from signedly.models.refresh_access_token_request import RefreshAccessTokenRequest
44
+ from signedly.models.request_count_page import RequestCountPage
45
+ from signedly.models.request_hit import RequestHit
46
+ from signedly.models.request_log import RequestLog
47
+ from signedly.models.request_log_page import RequestLogPage
48
+ from signedly.models.send_document200_response import SendDocument200Response
49
+ from signedly.models.send_document_by_link200_response import SendDocumentByLink200Response
50
+ from signedly.models.send_document_by_link_request import SendDocumentByLinkRequest
51
+ from signedly.models.send_document_request import SendDocumentRequest
52
+ from signedly.models.signatory import Signatory
53
+ from signedly.models.template import Template
54
+ from signedly.models.template_field import TemplateField
55
+ from signedly.models.template_page import TemplatePage
56
+ from signedly.models.update_document_field_by_body_request import UpdateDocumentFieldByBodyRequest
57
+ from signedly.models.update_document_field_by_body_request_items_inner import UpdateDocumentFieldByBodyRequestItemsInner
58
+ from signedly.models.update_webhook_endpoint_request import UpdateWebhookEndpointRequest
59
+ from signedly.models.upload import Upload
60
+ from signedly.models.upload_document_for_one_signer200_response import UploadDocumentForOneSigner200Response
61
+ from signedly.models.upload_document_for_one_signer_request import UploadDocumentForOneSignerRequest
62
+ from signedly.models.upload_document_request import UploadDocumentRequest
63
+ from signedly.models.webhook_delivery import WebhookDelivery
64
+ from signedly.models.webhook_delivery_page import WebhookDeliveryPage
65
+ from signedly.models.webhook_endpoint import WebhookEndpoint
66
+ from signedly.models.webhook_endpoint_with_secret import WebhookEndpointWithSecret
@@ -0,0 +1,105 @@
1
+ # coding: utf-8
2
+
3
+ """
4
+ Signedly API
5
+
6
+ The Signedly REST API lets your system upload documents, add signatories and fields, send them for signing and download the signed result. Every path starts with `/ap1/`, and every request and response body is JSON unless an endpoint says otherwise (the uploads are `multipart/form-data`). ## Authentication 1. In the Signedly web app, open **Account & Settings → API** and generate a **client ID** and **client secret** for your organisation. 2. `POST /ap1/token/` with them. You get an `access_token` (valid **2 hours**) and a `refresh_token` (valid **7 days**). While both are still valid, calling `/ap1/token/` again returns the same pair. 3. Send the access token on every other call: `Authorization: Bearer <access_token>`. 4. When the access token expires, `POST /ap1/refreshtoken/` with the refresh token for a new access token. When the refresh token has expired too, call `/ap1/token/` again. `/ap1/token/` and `/ap1/refreshtoken/` allow 60 calls a minute per IP address; more answer 429. A missing, unknown or expired access token answers 403 (`\"Client not found\"` or `\"Access token expired\"`). The API acts for your **organisation's admin account**: documents you upload belong to it and appear in its Signedly web app, and you can reach only that account's documents, templates, signatories and fields. Another organisation's IDs answer 404, as if they didn't exist. ## Plans What the API allows depends on the Signedly plan of your **organisation's admin account** (Account & Settings → Account & Plan). The same rules apply to live and test keys. | What | Free | Personal Pro | Business Pro | Teams | |---|---|---|---|---| | Generate live and test keys (Account & Settings → API) | – | ✓ | ✓ | ✓ | | Every endpoint, `/ap1/token/` and `/ap1/refreshtoken/` included | – | ✓ | ✓ | ✓ | | `require_email_otp` on `POST /ap1/signatories/` and `POST /ap1/signatories/bulk/` | – | ✓ | ✓ | ✓ | | Bulk send: `GET /ap1/bulk-sends/columns/` and `POST /ap1/bulk-sends/` | – | – | – | ✓ | The API is part of the paid plans. On Free (or with no plan) every call answers 403 `\"... Your plan doesn't include API access.\"`, with live or test keys, also with a token or keys made earlier; they work again once the plan is paid. On a paid plan, a feature it doesn't include answers 400 with `\"Your plan doesn't include ...\"` and changes nothing, and `GET /ap1/bulk-sends/{id}/` still reports bulk sends already made. Live documents also need an API contract with Signedly. Without one, or with an unpaid API invoice, `POST /ap1/upload/` (except templates), `/ap1/upload_app/`, `/ap1/documents/fromtemplate/` and `/ap1/bulk-sends/` answer 402 with live keys. Test keys work without a contract (see Sandbox). ## Sending a document for signing 1. `POST /ap1/upload/` a PDF or DOCX (`type` 2). The document is prepared in the background: find it in `GET /ap1/documents/?name=<name>` (its `upload.id` is the upload's `id`), and wait until `GET /ap1/documents/{id}/pages/` lists its pages. 2. `POST /ap1/signatories/` (one) or `POST /ap1/signatories/bulk/` (several) to add the people who sign. 3. `POST /ap1/documents/fields/` to place the fields each signatory fills in. 4. Send it: - `POST /ap1/document/send/` emails every signatory a signing link (with ordered signing, only the first; each next one is emailed in turn), or - `POST /ap1/document/send_url/` sends no email and returns the first signatory's signing link, for you to show or send yourself. 5. Poll `GET /ap1/documents-status-list/` (or `GET /ap1/documents/`) until the status is 6 (Completed), then `GET /ap1/document/download-link/` for the signed PDF and `GET /ap1/document/download-audit-link/` for its audit trail. **From a template:** upload with `type` 4 and a `template_name` (or make the template in the web app), place its fields with `POST /ap1/templates/fields/`, then for each signing make a document with `POST /ap1/documents/fromtemplate/`, add its signatory, and send it. **One signer, one call:** `POST /ap1/upload_app/` uploads a PDF or DOCX for one signer and returns their signing link in `redirect_url`; the signer places their own signature. After signing they go to the `redirect_url` you sent, and the signed PDF and its audit trail are emailed to `final_email` (otherwise to your organisation's admin). ## Quick start with curl Each step uses an ID from the step before. `$API` is this server, e.g. `https://l0ads.signedly.com`. ```bash # 1. Token curl -X POST $API/ap1/token/ -H 'Content-Type: application/json' \\ -d '{\"client_id\": \"<client id>\", \"client_secret\": \"<client secret>\"}' TOKEN=<access_token from the answer> # 2. Upload a PDF (answers with the upload's id) curl -X POST $API/ap1/upload/ -H \"Authorization: Bearer $TOKEN\" \\ -F file=@nda.pdf -F name=nda-ann-lee -F type=2 # 3. Find the document, then wait until it has pages curl \"$API/ap1/documents/?name=nda-ann-lee\" -H \"Authorization: Bearer $TOKEN\" DOC=<results[0].id> curl $API/ap1/documents/$DOC/pages/ -H \"Authorization: Bearer $TOKEN\" PAGE=<[0].id> # 4. Add the signatory curl -X POST $API/ap1/signatories/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"name\": \"Ann Lee\", \"email\": \"ann@example.com\"}' SIGNER=<id from the answer> # 5. Place her signature: 150 × 40 points, 72 points from the left, 640 from the top curl -X POST $API/ap1/documents/fields/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '[{\"document_id\": \"'$DOC'\", \"signatory_id\": \"'$SIGNER'\", \"kind\": 2, \"label\": \"Signature\", \"placeholder\": \"Sign here\", \"page\": \"'$PAGE'\", \"page_number\": 0, \"x\": 72, \"y\": 640, \"width\": 150, \"height\": 40}]' # 6. Send it (Ann gets the signing email) curl -X POST $API/ap1/document/send/ -H \"Authorization: Bearer $TOKEN\" \\ -H 'Content-Type: application/json' \\ -d '{\"document_id\": \"'$DOC'\", \"subject\": \"Please sign the NDA\", \"message\": \"Hi Ann, please sign by Friday.\", \"expiry_date\": \"2026-12-31\"}' # 7. Poll until status is 6 (Completed), then get the signed PDF curl \"$API/ap1/documents-status-list/?document_ids=$DOC\" -H \"Authorization: Bearer $TOKEN\" curl \"$API/ap1/document/download-link/?id=$DOC\" -H \"Authorization: Bearer $TOKEN\" ``` ## Postman Import the whole API into Postman with **Import → Link** and `<this server>/swaggerap1/postman.json`. Set `client_id` and `client_secret` in the collection's **Variables**, run **Get an access token** (it saves the token for every other request), and set `document_id` when a request needs one. ## Webhooks Instead of polling, add an endpoint with `POST /ap1/webhooks/` (or in **Account & Settings → API**) and Signedly posts your organisation's document events to it: `document.sent`, `document.viewed`, `document.signed`, `document.approved`, `document.completed`, `document.rejected` and `document.expired` (all of them, or the `events` you choose). Each is a JSON `POST`: ```json {\"id\": \"5b7f…\", \"type\": \"document.signed\", \"created_at\": \"2026-10-27T09:12:00+00:00\", \"test\": false, \"data\": {\"document\": {\"id\": \"6f0c…\", \"name\": \"nda.pdf\", \"status\": 5}, \"recipient\": {\"id\": \"0b6e…\", \"email\": \"ann@example.com\", \"name\": \"Ann Lee\", \"role\": \"signer\"}}} ``` `recipient` is null for events no recipient caused (sent, completed, expired); `test` is true for documents made with your test keys. Fetch anything else, such as download links, with your access token: events never carry links. **Check every event is from Signedly.** The `Signedly-Signature` header is `t=<unix seconds>,v1=<signature>`, where the signature is the hex HMAC-SHA256 of `<t>.<raw body>` with the endpoint's secret. Refuse an event whose signature doesn't match or whose `t` is more than 5 minutes off: ```python import hashlib, hmac, time def is_from_signedly(secret, header, raw_body): parts = dict(item.split(\"=\", 1) for item in header.split(\",\")) signed = f\"{parts['t']}.{raw_body.decode()}\".encode() expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() fresh = abs(time.time() - int(parts[\"t\"])) <= 300 return fresh and hmac.compare_digest(parts[\"v1\"], expected) ``` **Answer 2xx within 10 seconds**, then do the work. Anything else is retried after 1 and 5 minutes, then 30 minutes and 2, 5 and 10 hours (7 tries in about 18 hours). `Signedly-Event-Id` is the same on every try of an event: use it to ignore repeats. After 20 events in a row fail for good, Signedly switches the endpoint off and emails your organisation's admin; switch it on again with `PUT /ap1/webhooks/{id}/` and `\"is_active\": true`. Each endpoint's deliveries and their last answers are at `GET /ap1/webhooks/{id}/deliveries/`, and any can be sent again. ## Sandbox Build and test against the API without paying for documents: in **Account & Settings → API**, generate your **test keys**, and get a token with them at `/ap1/token/` as usual. Everything works the same, except that what you upload or make from a template with a test token is a **test document** (`is_test` on its upload): - every page of its PDF and of its audit trail says **TEST – NOT LEGALLY BINDING**; - its emails are real, with `[TEST]` at the start of the subject; - it isn't billed or counted toward your plan; - your organisation can make 50 a calendar month (templates don't count); the next upload answers 429. ## Fields Positions and sizes are in **PDF points** (1/72 inch), measured from the **top-left corner** of the page as it is displayed (rotation applied). `page_number` counts pages from 0. A field must sit wholly on its page (1 point of tolerance); otherwise it is refused with 400. A field's page and signatory can't be changed later: delete the field and add it again. ## Status values **Document `status`:** 1 Draft · 2 Signees Added · 3 Prepared · 4 Sent · 5 In Progress · 6 Completed · 7 Rejected · 8 Archived · 9 Expired. Signatories, fields and sends are only accepted while a document is 1–3 (not yet sent). **Signatory `status`:** 1 Waiting · 2 Invited · 3 Signed · 4 Viewed · 5 Rejected. ## Lists `GET /ap1/documents/`, `/ap1/documents-status-list/`, `/ap1/templates/`, `/ap1/logs/` and `/ap1/logs/hits/` are paged: pass `limit` (default 10) and `offset`, and read `count`, `next`, `previous` and `results` from the response. ## Errors | Status | Meaning | |---|---| | 400 | The request was refused, also when your plan doesn't include it (see Plans); the body says why (`{\"error\": \"...\"}`, or the name of each bad field with its messages). Nothing was changed. | | 403 | The access token is missing, unknown or expired; the client ID and secret or the refresh token were refused; the organisation's plan has no API access (Free, see Plans); or an `expiry_date` isn't in the future (`\"Invalid Date Entered\"`). | | 402 | No API contract, or an unpaid API invoice: live documents are refused (test keys keep working). | | 404 | The document, template, signatory or field doesn't exist or isn't yours. | | 429 | Too many token requests (wait a minute), or this month's 50 test documents are used. | | 5xx | Our side failed; retry later. | A send that times out may still have worked: check the document's status before sending again (a second send of a sent document answers 400). Download, view and audit links are valid for about 7 days; ask for a new one whenever you need it.
7
+
8
+ The version of the OpenAPI document: v1
9
+ Contact: info@signedly.com
10
+ Generated by OpenAPI Generator (https://openapi-generator.tech)
11
+
12
+ Do not edit the class manually.
13
+ """ # noqa: E501
14
+
15
+
16
+ from __future__ import annotations
17
+ import pprint
18
+ import re # noqa: F401
19
+ import json
20
+
21
+ from datetime import date
22
+ from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt, StrictStr
23
+ from typing import Any, ClassVar, Dict, List, Optional
24
+ from typing import Optional, Set
25
+ from typing_extensions import Self
26
+
27
+ class CreateBulkSend202Response(BaseModel):
28
+ """
29
+ CreateBulkSend202Response
30
+ """ # noqa: E501
31
+ documents: Optional[List[Dict[str, Any]]] = Field(default=None, description="Each document: id, status and its signatories' email and status.")
32
+ documents_made: Optional[StrictInt] = Field(default=None, description="Documents made and sent so far.")
33
+ failed_rows: Optional[List[Dict[str, Any]]] = Field(default=None, description="Rows that couldn't be sent, with why.")
34
+ id: Optional[StrictStr] = Field(default=None, description="The bulk send's ID.")
35
+ is_test: Optional[StrictBool] = Field(default=None, description="Sent with test keys: its documents are test documents.")
36
+ sent_at: Optional[date] = Field(default=None, description="The day it was sent.")
37
+ status: Optional[StrictInt] = Field(default=None, description="1 Created · 2 CSV Uploaded · 3 Sent · 4 Ready")
38
+ template_id: Optional[StrictStr] = Field(default=None, description="Its template.")
39
+ total_documents: Optional[StrictInt] = Field(default=None, description="Rows in the file: one document each.")
40
+ __properties: ClassVar[List[str]] = ["documents", "documents_made", "failed_rows", "id", "is_test", "sent_at", "status", "template_id", "total_documents"]
41
+
42
+ model_config = ConfigDict(
43
+ populate_by_name=True,
44
+ validate_assignment=True,
45
+ protected_namespaces=(),
46
+ )
47
+
48
+
49
+ def to_str(self) -> str:
50
+ """Returns the string representation of the model using alias"""
51
+ return pprint.pformat(self.model_dump(by_alias=True))
52
+
53
+ def to_json(self) -> str:
54
+ """Returns the JSON representation of the model using alias"""
55
+ # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
56
+ return json.dumps(self.to_dict())
57
+
58
+ @classmethod
59
+ def from_json(cls, json_str: str) -> Optional[Self]:
60
+ """Create an instance of CreateBulkSend202Response from a JSON string"""
61
+ return cls.from_dict(json.loads(json_str))
62
+
63
+ def to_dict(self) -> Dict[str, Any]:
64
+ """Return the dictionary representation of the model using alias.
65
+
66
+ This has the following differences from calling pydantic's
67
+ `self.model_dump(by_alias=True)`:
68
+
69
+ * `None` is only added to the output dict for nullable fields that
70
+ were set at model initialization. Other fields with value `None`
71
+ are ignored.
72
+ """
73
+ excluded_fields: Set[str] = set([
74
+ ])
75
+
76
+ _dict = self.model_dump(
77
+ by_alias=True,
78
+ exclude=excluded_fields,
79
+ exclude_none=True,
80
+ )
81
+ return _dict
82
+
83
+ @classmethod
84
+ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
85
+ """Create an instance of CreateBulkSend202Response from a dict"""
86
+ if obj is None:
87
+ return None
88
+
89
+ if not isinstance(obj, dict):
90
+ return cls.model_validate(obj)
91
+
92
+ _obj = cls.model_validate({
93
+ "documents": obj.get("documents"),
94
+ "documents_made": obj.get("documents_made"),
95
+ "failed_rows": obj.get("failed_rows"),
96
+ "id": obj.get("id"),
97
+ "is_test": obj.get("is_test"),
98
+ "sent_at": obj.get("sent_at"),
99
+ "status": obj.get("status"),
100
+ "template_id": obj.get("template_id"),
101
+ "total_documents": obj.get("total_documents")
102
+ })
103
+ return _obj
104
+
105
+