{ "aid": "spotdraft.com:main-v1", "name": "SpotDraft API", "type": "Index", "description": "## SpotDraft Public API\n\n## API Reference\n\nThe SpotDraft API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts [form-encoded]() request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes, authentication, and verbs.\n\n### Note on redirects\n\nOur API will respond with `302 Found` if a redirect is needed. There are two situations in which this usually happens:\n\n- If the API is accessed using `http` instead of `https`.\n- If a trailing slash is added or removed in a way that is inconsitent with this documentation.\n\nCertain libraries can have unexpected behavior if they encounter a redirect.\n\nFor example the python `requests` library will follow the redirect but not using the same HTTP Verb, and instead falling back on `GET`. This can lead to hard to debug issues where the API is seemingly responding with an unexpected body and response code. It is thus advisable to configure `requests` (or any other library) to not follow redirects and instead fail the request if it encounters a redirect. This can be achieved by passing `allow_redirects=False` when making the request (in case of python `requests`).\n\n## Authentication\n\nAll API requests expect a Client ID to be sent as a HTTP Header.\n\n**Requests as the Application**\n\nIn addition to the Client ID, a Client Secret must also be sent in the HTTP Headers. All requests made using this method will be audited as the calling Application.\n\nWhen making requests as the Application, the Application can impersonate a user by passing the `user-email` header with the email\naddress of the user to impersonate. The user must be an active member of the workspace for this to work.\n\nIf impersonation is not used the Application will act as the user who is linked to the credentials. This can be updated by reaching\nout to your Customer Success Associate.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Type\n Params\n Values\n
HEADER\n client-id\n string\n
HEADER\n client-secret\n string\n
HEADER\n user-email\n string (optional)\n
\n\n\\*\\*(Client-Secret must be set in addition to Client-Id)\n\n## Webhooks\n\nThe SpotDraft API allows API Consumers to receive webhooks when certain actions are taken by Users on the platform.\n\nAt the time of writing webhooks need to be enabled by the SpotDraft Customer Success team. Please reach out to your CS Manager if you need access to this.\n\n**Webhook Schemantics**\n\n- The URL provided must have HTTPS with a valid certificate. Self-signed certificates are not accepted.\n- The webhook will be paused if more than 5 failures occur for a given URL.\n- Multiple webhook URLs can be added for a given SpotDraft account.\n- It is possible to filter to a specific subset of activities to get webhooks on.\n\n**Verifying Webhooks**\n\nAll requests sent by SpotDraft to your server include the header X-SD-CONTENT-HASH which can be used to verify that the webhook was sent by SpotDraft. \\\n \\\nThe content of the X-SD-CONTENT-HASH header is created by computing the HMAC-SHA512 on the JSON payload using the Callback Secret which is shared privately. \\\n \\\nIt can be verified by generating a using the same process on the Consumer end and ensuring that the signatures match. A Python snippet is provided below for clarity.\n\n```\nimport hmac\nimport hashlib\n\nhmac_instance = hmac.new(\n callback_secret.encode(\"utf-8\"),\n request.body,\n digestmod=hashlib.sha512,\n)\nsignature = hmac_instance.hexdigest()\n\nassert signature == request.headers[\"X-SD-CONTENT-HASH\"]\n```\n\n### Webhook Activity Types\n\nThe following are the different activies for which webhooks are sent. The table is sorted by the order in which these activity events are expected.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
activity field valueDetails
CONTRACT_CREATEDWhen a contract is created
CONTRACT_SENT_TO_COUNTERPARTYWhen the contract is sent via email to the counterparty for review
REDLINING_EMAIL_DELIVEREDWhen the email sent to the counterparty for review is delivered
REDLINING_EMAIL_NOT_DELIVEREDWhen the email sent to the counterparty for review could not be delivered for some reason
REDLINING_EMAIL_OPENEDWhen the contract sent to the counterparty for review is opened
REDLINING_EMAIL_LINK_CLICKEDWhen the counterparty clicks on the contract link sent for review
CONTRACT_SIGNATURE_REQUESTEDWhen a contract is sent for signature
CONTRACT_SIGNATURE_REQUESTED_NOTIFICATION_SENTWhen someone is notified that they need to add their signature. One per signatory who receives the email
SIGNING_EMAIL_DELIVEREDWhen the email sent to the counterparty for signing is delivered
SIGNING_EMAIL_NOT_DELIVEREDWhen the email sent to the counterparty for signing could not be delivered for some reason
SIGNING_EMAIL_OPENEDWhen the contract sent to the counterparty for signing is opened
SIGNING_EMAIL_LINK_CLICKEDWhen the counterparty clicks on the contract link sent for singing
CONTRACT_SIGNEDWhen any user signs a contract
CONTRACT_EXECUTEDWhen all signatures are collected
CONTRACT_DELETEDWhen a contract is moved to the deleted tab
CONTRACT_SIGNATURE_DECLINEDWhen a user declines to sign a contract
\n\n### Webhook Payload\n\nSee the [webhook section](https://api.spotdraft.com)\n\n## Errors\n\nThe SpotDraft API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with SpotDraft's servers (these are rare).\n\n**HTTP Status Code Summary**\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
200 - OK\n Everything worked as expected.\n
400 - Bad Request\n The request was unacceptable, often due to missing a required parameter.\n
401 - Unauthorized\n No valid API key provided.\n
402 - Request Failed\n The parameters were valid but the request failed.\n
403 - Forbidden\n The API key doesn't have permissions to perform the request.\n
404 - Not Found\n The requested resource doesn't exist.\n
409 - Conflict\n The request conflicts with another request (perhaps due to using the same idempotent key).\n
429 - Too Many Requests\n Too many requests hitting the API, exceeding the rate limit of 10 requests/second. We recommend an exponential backoff of your requests.\n
500, 502, 503, 504 - Server Errors\n Something went wrong on SpotDraft’s end. (These are rare.)\n
\n\n## Embedded Contract API\n\nThis section explains the steps to integrate SpotDraft\\'s Embedded\nsigning experience into your app.\n\n#### Step 1. Creating a Contract from the data collected\n\n
    \n
  1. \n Authentication\n

    The API credentials (client-id and client-secret) should be generated by the user who needs to receive notifications when a user signs agreements using Embedded. The same user will also be assigned as the Business User for all contracts created using this flow. Please refer to Authentication for more details.

    \n

    2. \n
  2. \n Payload\n

    Once a user fills out the form on your web application, the information provided by them should be passed to the SpotDraft Create Contract API.

    \n
    3. \n
\n\n#### Step 2. Generate URL\n\nThe call to [Create Contract API](#operation/v2.1_public_contracts_create) made in previous step will return a Contract ID in the response payload. This Contract ID and the email address of the counterparty need to be passed to the [Counterparty Embedded Url](#operation/v2.1_public_contracts_embedded_contracts_counter_party_list) to get the URL which can be iframed in your application.\n\n#### Step 3. Render & Close iframe\n\nThe call to [CounterParty Embedded Url](#operation/v2.1_public_contracts_embedded_contracts_counter_party_list) made in previous step will return a url that can be used to render the iframe. Once the SpotDraft signing experience gets loaded in the iframe, SpotDraft will emit messages using the [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API to allow your app to react to user actions in the SpotDraft Embedded flow. The following messages are emitted.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
EventMessage NamePayload
Sign Completed Successfullyspotdraft.embedded.sign_successful{contract_id}
Sign Declined by Userspotdraft.embedded.sign_declined{contract_id}
Sign API Failspotdraft.embedded.sign_error{contract_id, error: {code, upstream_error}}

\n code: SD_SIGN_API_ERROR\n
PDF Generation Failspotdraft.embedded.sign_error{contract_id, error: {code, upstream_error}}

\n code: SD_SIGN_DOC_GENERATION_ERROR\n
\n\n### Points to be noted\n\n\n\n## Spotdraft Clickthrough SDK\n\n### Introduction\n\nThe Clickthrough JavaScript SDK allows developers to integrate Clickthrough functionality into their web applications. Clickthrough enables you to require users to acknowledge contractual agreements before proceeding with certain actions.\n\nThis documentation provides instructions on how to include and use the Clickthrough JavaScript SDK in your web application.\n\n### Getting Started\n\n#### Prerequisites\n\nBefore you start integrating the Clickthrough JavaScript SDK, make sure you have the following prerequisites in place:\n\n- A SpotDraft Clickthrough account: To use the Clickthrough JavaScript SDK, you need an active SpotDraft Clickthrough account. If you don't have one, you can request a demo by visiting https://www.spotdraft.com/requestfordemo. This account is necessary for creating Clickthroughs and managing contracts.\n - Clickthrough creation: Within your SpotDraft Clickthrough account, you should have created atleast one Clickthrough. A Clickthrough represents the agreement that your end users will be consenting to. Make sure to configure the necessary contract details, such as name, content, and any other relevant information.\n - Contract addition: Within your Clickthrough, you need to add contracts that will be a part of the Clickthrough. These contracts define the specific terms and conditions or legal agreements that users must accept.\n- Supported Domains: In the `Clickthrough Settings` tab of your Clickthrough, ensure that you have added the domains where your Clickthrough will be hosted to `Supported Domains`.\n - For example, if your Clickthrough will be hosted on `https://my_domain.com/clickwraps/test.html`, make sure to add `my_domain.com` to `Supported Domains`.\n- Development environment with SSL enabled\n - To ensure secure communication between your web application and the Clickthrough JavaScript SDK, it is recommended to have SSL (HTTPS) enabled in your development environment. This ensures that the SDK functions properly and maintains data privacy and security.\n\n### Installation\n\n> **_NOTE:_** All the following code snippets, with the right values for each, can be directly copied from the Spotdraft Clickthrough console by clicking on the `View Snippet` on the Clickthrough page.\n\nAdd the following script tag to your HTML file (ideally in the head tag) to include the SDK:\n\n```\n\n```\n\n`SdClickthrough` class will be attached to the window and spotdraft Clickthrough will be loaded into your application.\n\n### Initialization\n\nYou must initialize the Spotdraft Clickthrough SDK to include it in your application.\n\n- Initialise `new SdClickthrough` instance to configure the SDK.\n - Provide the `clickwrapId`, `hostLocationDomId`, and `baseUrl` as shown in the example below:\n - `clickwrapId` - `UUID` - The Clickthrough public ID from the Clickthrough settings page on SD.\n - `hostLocationDomId` - `str` - The ID of the dom element where you want to load the Clickthrough.\n - `baseUrl` - `str` - You can find the base URL on clicking the `View Snippet` on the Clickthrough settings page on SD.\n- Use the `init` method to attach the clickthrough to the HTML DOM.\n\n```\nwindow.addEventListener(\"sdClickthroughLoaded\", function () {\n const clickthrough = new SdClickthrough({\n clickwrapId: \"CLICKWRAP_ID_FROM_CONSOLE\",\n hostLocationDomId: \"HOST_ELEMENT_DOM_ID\",\n baseUrl: \"BASE_URL_FROM_CONSOLE\"\n });\n clickthrough.init();\n})\n```\n\n### Creating Clickthrough Contract\n\nThe `submit` method enables you to create a Clickthrough contract based on the provided agreement. Here's an example of how to use the submit method to create a Clickthrough contract:\n\n```\n// Define the payload object\nconst payload = {\n user_identifier: 'johndoe@example.com', // this is a required field\n first_name: 'John',\n last_name: 'Doe',\n user_email: 'johndoe@example.com',\n};\n\nclickthrough.submit(payload).then(data => {\n\t// continue to submit the form\n})\n```\n\n> **_NOTE:_** `user_identifier` is a required field and its data type is string. It can be an email, phone number or anything else that uniquely identifies a user on your system.\n\n### Checking Clickthrough Agreement Acceptance\n\nAfter showing the user the Clickthrough agreement, you might want to restrict some operations, including submitting forms, until they have accepted the agreement. The 'isAccepted()' method of the SDK enables you to determine whether a particular Clickthrough agreement has been accepted by the user. Here is how to apply it:\n\n```\nif(clickthrough.isAccepted) {\n // continue submitting your form\n}\n```\n\n### Passing Custom User Data\n\nThe Spotdraft Clickthrough SDK enables you to create Clickthrough contracts in Spotdraft with customized payload data in addition to obtaining user approval. You can send a payload object to the submit method to be linked to the newly generated Clickthrough contract. Any additional data or metadata pertinent to your application or operational procedures may be included in this payload.\n\nAs part of the submit payload\n\n```\nconst payload = {\n user_identifier: '123',\n ...\n additional_custom_information: {\n customField1: 'Value 1',\n customField2: 'Value 2',\n // Add more custom fields as needed\n },\n};\n\nclickthrough.submit(payload).then(data => {\n\t// continue to submit the form\n})\n```\n\n### Styling Clickthrough Elements\n\nYou can utilize the class names provided by the Spotdraft Clickthrough SDK to style the items that the SDK renders. To make these elements match the appearance and feel of your application, you can apply unique CSS styles. The list of class names includes:\n\n- sd-clickthrough-checkbox: This class name can be used to target the checkbox element rendered by the SDK.\n\n- sd-clickthrough-text: This class name can be used to target the text content displayed in the Clickthrough agreement.\n\n### Event Handling\n\nYou can listen to events provided by the Spotdraft Clickthrough SDK in order to carry out particular tasks or react to user activities. To add event listeners to the SDK and record these events, use the 'on' method. Here's an example:\n\n```\nclickthrough.on(\"sdClickthroughLoaded\", function (data) {\n // Event listener callback function\n console.log(\"Clickthrough object loaded succesfully!!\");\n});\n```\n\nThe followings are the type of events you can listen to:\n\n- acceptanceToggled - When users checks/unchecks the checkbox.\n- sdClickthroughLoaded - When Spotdraft Clickthrough object successfully loads.\n- sdClickthroughLoadFailed - When Spotdraft Clickthrough object failed to load.\n\n### Full example\n\n```\n\n \n \n \n \n
\n \n \n
\n \n
\n \n \n\n\n```\n\n## Clickthrough KeyPointers\n\n### Generating Reports for Clickthrough Contracts\n\nYou have the option to create reports for Clickthrough contracts on SpotDraft using Key Pointers for each specific Clickthrough Packet. Before using this API, make sure to set up the necessary key pointers for your Clickthrough packet\n\n### Passing Data to Key Pointers\n\nTo send data from your website to a Clickthrough Packet's key pointer, use the `key_pointer_information` field in the clickthrough API payload. Data should be in key-value pairs. The values will be checked against their respective key pointer types for validation.\n\n### Validation and Display\n\nIf the validation fails, the key pointer values won't be shown in the key pointer section. However, this won't cause the contract generation to fail. You can find a list of key pointer values in the table below.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
KeyPointer TypesSyntaxSample
STRING“keypointer_field_name”: “Any_string_value”“slug_name”: \"Harvey Specter\"
DATE“keypointer_field_name”: “YYYY-MM-DD”

NB: Date should be in the aforementioned format as a string.		\"slug_dob\": \"2023-01-01\"
NUMBER“keypointer_field_name”: Integer\"slug_age\":24
CHECK BOX“keypointer_field_name”: bool“slug_is_admin”: true
CURRENCY“keypointer_field_name”:{ \"type\": \"Currency_type_code\", \"value\": Integer} \"slug_salary\": {\"type\": \"USD\", \"value\": 1000}
PHONE NUMBER“keypointer_field_name”:\n{\"number\": \"number_value\",\n\"country_code\": \"country_code_string\",\"code\": \"country_code_integer\"}\"slug_mobile\": {\"number\": \"9999912345\",\"country_code\": \"IN\",\"code\": \"+91\"}\n
DURATION“keypointer_field_name”: {\"days\": Integer, \"type\": \"DAY /WEEK / MONTH /YEARS\", \"value\": Integer}“slug_term”:\n{\"days\": 730, \"type\": \"YEARS\", \"value\": 2}\n
DROPDOWN“keypointer_field_name”: “value”

NB:Value should be in the dropdown list.		\"slug_country\": \"India\"\n
MULTI DROPDOWN“keypointer_field_name”: [“value1”, “value2”]

NB:Value1 and Value2 should be in the multi-dropdown list.		\"slug_multi\": [\"L1\",\"L2\"]\n
PARAGRAPHkeypointer_field_name”: “Any_string_values”“slug_paragraph: “It’s Paragraph KP”\n
\n\n## Clickthrough Agreement Reacceptance\n\nThe \"Clickthrough Re-Acceptance\" feature enables users to gather re-acceptance for the currently published version of the agreement. This allows users to obtain acceptance from individuals who have previously agreed to any earlier versions.\n\nUsers have the capability to specify whether a currently published version requires re-acceptance, both during the publishing process and after the current version is published. It's important to note that at any given time, only the latest published version can be designated for re-acceptance.\n\nOnce re-acceptance is collected, the SDK will provide users with information indicating whether a specific user has accepted the currently published version of the agreement. This information can be utilized to trigger a pop-up for re-acceptance or to notify users about modifications made to the prior agreement version.\n\nThe `isReacceptanceRequired` method of the SDK enables you to determine whether the current user needs to reaccept the updated agreement or not:\n\n```\nclickthrough.isReacceptanceRequired()\n .then(status) {\n // check if reaccapence is required or not\n if (status.trigger_acceptance) {\n // show the clickthrough elements\n // so users can reaccept the updated agreements\n clickthrough.init();\n }\n }\n```\n", "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/spotdraft.com/main/v1/apis.json", "tags": [ "spotdraft.com", "main" ], "created": "2026-03-30", "modified": "2026-03-30", "specificationVersion": "0.19", "access": "3rd-Party", "maintainers": [ { "FN": "Jentic", "X-github": "jentic", "url": "https://github.com/jentic" } ], "apis": [ { "aid": "spotdraft.com:main-v1", "name": "SpotDraft API", "description": "## SpotDraft Public API\n\n## API Reference\n\nThe SpotDraft API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts [form-encoded]() request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes, authentication, and verbs.\n\n### Note on redirects\n\nOur API will respond with `302 Found` if a redirect is needed. There are two situations in which this usually happens:\n\n- If the API is accessed using `http` instead of `https`.\n- If a trailing slash is added or removed in a way that is inconsitent with this documentation.\n\nCertain libraries can have unexpected behavior if they encounter a redirect.\n\nFor example the python `requests` library will follow the redirect but not using the same HTTP Verb, and instead falling back on `GET`. This can lead to hard to debug issues where the API is seemingly responding with an unexpected body and response code. It is thus advisable to configure `requests` (or any other library) to not follow redirects and instead fail the request if it encounters a redirect. This can be achieved by passing `allow_redirects=False` when making the request (in case of python `requests`).\n\n## Authentication\n\nAll API requests expect a Client ID to be sent as a HTTP Header.\n\n**Requests as the Application**\n\nIn addition to the Client ID, a Client Secret must also be sent in the HTTP Headers. All requests made using this method will be audited as the calling Application.\n\nWhen making requests as the Application, the Application can impersonate a user by passing the `user-email` header with the email\naddress of the user to impersonate. The user must be an active member of the workspace for this to work.\n\nIf impersonation is not used the Application will act as the user who is linked to the credentials. This can be updated by reaching\nout to your Customer Success Associate.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Type\n Params\n Values\n
HEADER\n client-id\n string\n
HEADER\n client-secret\n string\n
HEADER\n user-email\n string (optional)\n
\n\n\\*\\*(Client-Secret must be set in addition to Client-Id)\n\n## Webhooks\n\nThe SpotDraft API allows API Consumers to receive webhooks when certain actions are taken by Users on the platform.\n\nAt the time of writing webhooks need to be enabled by the SpotDraft Customer Success team. Please reach out to your CS Manager if you need access to this.\n\n**Webhook Schemantics**\n\n- The URL provided must have HTTPS with a valid certificate. Self-signed certificates are not accepted.\n- The webhook will be paused if more than 5 failures occur for a given URL.\n- Multiple webhook URLs can be added for a given SpotDraft account.\n- It is possible to filter to a specific subset of activities to get webhooks on.\n\n**Verifying Webhooks**\n\nAll requests sent by SpotDraft to your server include the header X-SD-CONTENT-HASH which can be used to verify that the webhook was sent by SpotDraft. \\\n \\\nThe content of the X-SD-CONTENT-HASH header is created by computing the HMAC-SHA512 on the JSON payload using the Callback Secret which is shared privately. \\\n \\\nIt can be verified by generating a using the same process on the Consumer end and ensuring that the signatures match. A Python snippet is provided below for clarity.\n\n```\nimport hmac\nimport hashlib\n\nhmac_instance = hmac.new(\n callback_secret.encode(\"utf-8\"),\n request.body,\n digestmod=hashlib.sha512,\n)\nsignature = hmac_instance.hexdigest()\n\nassert signature == request.headers[\"X-SD-CONTENT-HASH\"]\n```\n\n### Webhook Activity Types\n\nThe following are the different activies for which webhooks are sent. The table is sorted by the order in which these activity events are expected.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
activity field valueDetails
CONTRACT_CREATEDWhen a contract is created
CONTRACT_SENT_TO_COUNTERPARTYWhen the contract is sent via email to the counterparty for review
REDLINING_EMAIL_DELIVEREDWhen the email sent to the counterparty for review is delivered
REDLINING_EMAIL_NOT_DELIVEREDWhen the email sent to the counterparty for review could not be delivered for some reason
REDLINING_EMAIL_OPENEDWhen the contract sent to the counterparty for review is opened
REDLINING_EMAIL_LINK_CLICKEDWhen the counterparty clicks on the contract link sent for review
CONTRACT_SIGNATURE_REQUESTEDWhen a contract is sent for signature
CONTRACT_SIGNATURE_REQUESTED_NOTIFICATION_SENTWhen someone is notified that they need to add their signature. One per signatory who receives the email
SIGNING_EMAIL_DELIVEREDWhen the email sent to the counterparty for signing is delivered
SIGNING_EMAIL_NOT_DELIVEREDWhen the email sent to the counterparty for signing could not be delivered for some reason
SIGNING_EMAIL_OPENEDWhen the contract sent to the counterparty for signing is opened
SIGNING_EMAIL_LINK_CLICKEDWhen the counterparty clicks on the contract link sent for singing
CONTRACT_SIGNEDWhen any user signs a contract
CONTRACT_EXECUTEDWhen all signatures are collected
CONTRACT_DELETEDWhen a contract is moved to the deleted tab
CONTRACT_SIGNATURE_DECLINEDWhen a user declines to sign a contract
\n\n### Webhook Payload\n\nSee the [webhook section](https://api.spotdraft.com)\n\n## Errors\n\nThe SpotDraft API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with SpotDraft's servers (these are rare).\n\n**HTTP Status Code Summary**\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
200 - OK\n Everything worked as expected.\n
400 - Bad Request\n The request was unacceptable, often due to missing a required parameter.\n
401 - Unauthorized\n No valid API key provided.\n
402 - Request Failed\n The parameters were valid but the request failed.\n
403 - Forbidden\n The API key doesn't have permissions to perform the request.\n
404 - Not Found\n The requested resource doesn't exist.\n
409 - Conflict\n The request conflicts with another request (perhaps due to using the same idempotent key).\n
429 - Too Many Requests\n Too many requests hitting the API, exceeding the rate limit of 10 requests/second. We recommend an exponential backoff of your requests.\n
500, 502, 503, 504 - Server Errors\n Something went wrong on SpotDraft’s end. (These are rare.)\n
\n\n## Embedded Contract API\n\nThis section explains the steps to integrate SpotDraft\\'s Embedded\nsigning experience into your app.\n\n#### Step 1. Creating a Contract from the data collected\n\n
    \n
  1. \n Authentication\n

    The API credentials (client-id and client-secret) should be generated by the user who needs to receive notifications when a user signs agreements using Embedded. The same user will also be assigned as the Business User for all contracts created using this flow. Please refer to Authentication for more details.

    \n

    2. \n
  2. \n Payload\n

    Once a user fills out the form on your web application, the information provided by them should be passed to the SpotDraft Create Contract API.

    \n
    3. \n
\n\n#### Step 2. Generate URL\n\nThe call to [Create Contract API](#operation/v2.1_public_contracts_create) made in previous step will return a Contract ID in the response payload. This Contract ID and the email address of the counterparty need to be passed to the [Counterparty Embedded Url](#operation/v2.1_public_contracts_embedded_contracts_counter_party_list) to get the URL which can be iframed in your application.\n\n#### Step 3. Render & Close iframe\n\nThe call to [CounterParty Embedded Url](#operation/v2.1_public_contracts_embedded_contracts_counter_party_list) made in previous step will return a url that can be used to render the iframe. Once the SpotDraft signing experience gets loaded in the iframe, SpotDraft will emit messages using the [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API to allow your app to react to user actions in the SpotDraft Embedded flow. The following messages are emitted.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
EventMessage NamePayload
Sign Completed Successfullyspotdraft.embedded.sign_successful{contract_id}
Sign Declined by Userspotdraft.embedded.sign_declined{contract_id}
Sign API Failspotdraft.embedded.sign_error{contract_id, error: {code, upstream_error}}

\n code: SD_SIGN_API_ERROR\n
PDF Generation Failspotdraft.embedded.sign_error{contract_id, error: {code, upstream_error}}

\n code: SD_SIGN_DOC_GENERATION_ERROR\n
\n\n### Points to be noted\n\n
    \n
  • \n Loader\n

    As generating large contracts can take a few seconds, we recommend showing a loader or progress indicator in your application to provide users a visual cue while your app is waiting for the completion of the initial API calls for the Embedded flow. The approach for implementing this loader depends on your app and tech stack.

    \n

    • \n
  • \n Cluster Id\n

    To best serve our users in different regions and be compliant with data residency requirements, we have multiple data centres. The following are the region and the relevant Id:

    \n
      \n
    • \n USA: us\n
      • \n
    • \n Europe: eu\n
      • \n
    • \n India: in\n
      • \n
    • \n Middle East: me\n
      • \n
    \n
    • \n
\n\n## Spotdraft Clickthrough SDK\n\n### Introduction\n\nThe Clickthrough JavaScript SDK allows developers to integrate Clickthrough functionality into their web applications. Clickthrough enables you to require users to acknowledge contractual agreements before proceeding with certain actions.\n\nThis documentation provides instructions on how to include and use the Clickthrough JavaScript SDK in your web application.\n\n### Getting Started\n\n#### Prerequisites\n\nBefore you start integrating the Clickthrough JavaScript SDK, make sure you have the following prerequisites in place:\n\n- A SpotDraft Clickthrough account: To use the Clickthrough JavaScript SDK, you need an active SpotDraft Clickthrough account. If you don't have one, you can request a demo by visiting https://www.spotdraft.com/requestfordemo. This account is necessary for creating Clickthroughs and managing contracts.\n - Clickthrough creation: Within your SpotDraft Clickthrough account, you should have created atleast one Clickthrough. A Clickthrough represents the agreement that your end users will be consenting to. Make sure to configure the necessary contract details, such as name, content, and any other relevant information.\n - Contract addition: Within your Clickthrough, you need to add contracts that will be a part of the Clickthrough. These contracts define the specific terms and conditions or legal agreements that users must accept.\n- Supported Domains: In the `Clickthrough Settings` tab of your Clickthrough, ensure that you have added the domains where your Clickthrough will be hosted to `Supported Domains`.\n - For example, if your Clickthrough will be hosted on `https://my_domain.com/clickwraps/test.html`, make sure to add `my_domain.com` to `Supported Domains`.\n- Development environment with SSL enabled\n - To ensure secure communication between your web application and the Clickthrough JavaScript SDK, it is recommended to have SSL (HTTPS) enabled in your development environment. This ensures that the SDK functions properly and maintains data privacy and security.\n\n### Installation\n\n> **_NOTE:_** All the following code snippets, with the right values for each, can be directly copied from the Spotdraft Clickthrough console by clicking on the `View Snippet` on the Clickthrough page.\n\nAdd the following script tag to your HTML file (ideally in the head tag) to include the SDK:\n\n```\n\n```\n\n`SdClickthrough` class will be attached to the window and spotdraft Clickthrough will be loaded into your application.\n\n### Initialization\n\nYou must initialize the Spotdraft Clickthrough SDK to include it in your application.\n\n- Initialise `new SdClickthrough` instance to configure the SDK.\n - Provide the `clickwrapId`, `hostLocationDomId`, and `baseUrl` as shown in the example below:\n - `clickwrapId` - `UUID` - The Clickthrough public ID from the Clickthrough settings page on SD.\n - `hostLocationDomId` - `str` - The ID of the dom element where you want to load the Clickthrough.\n - `baseUrl` - `str` - You can find the base URL on clicking the `View Snippet` on the Clickthrough settings page on SD.\n- Use the `init` method to attach the clickthrough to the HTML DOM.\n\n```\nwindow.addEventListener(\"sdClickthroughLoaded\", function () {\n const clickthrough = new SdClickthrough({\n clickwrapId: \"CLICKWRAP_ID_FROM_CONSOLE\",\n hostLocationDomId: \"HOST_ELEMENT_DOM_ID\",\n baseUrl: \"BASE_URL_FROM_CONSOLE\"\n });\n clickthrough.init();\n})\n```\n\n### Creating Clickthrough Contract\n\nThe `submit` method enables you to create a Clickthrough contract based on the provided agreement. Here's an example of how to use the submit method to create a Clickthrough contract:\n\n```\n// Define the payload object\nconst payload = {\n user_identifier: 'johndoe@example.com', // this is a required field\n first_name: 'John',\n last_name: 'Doe',\n user_email: 'johndoe@example.com',\n};\n\nclickthrough.submit(payload).then(data => {\n\t// continue to submit the form\n})\n```\n\n> **_NOTE:_** `user_identifier` is a required field and its data type is string. It can be an email, phone number or anything else that uniquely identifies a user on your system.\n\n### Checking Clickthrough Agreement Acceptance\n\nAfter showing the user the Clickthrough agreement, you might want to restrict some operations, including submitting forms, until they have accepted the agreement. The 'isAccepted()' method of the SDK enables you to determine whether a particular Clickthrough agreement has been accepted by the user. Here is how to apply it:\n\n```\nif(clickthrough.isAccepted) {\n // continue submitting your form\n}\n```\n\n### Passing Custom User Data\n\nThe Spotdraft Clickthrough SDK enables you to create Clickthrough contracts in Spotdraft with customized payload data in addition to obtaining user approval. You can send a payload object to the submit method to be linked to the newly generated Clickthrough contract. Any additional data or metadata pertinent to your application or operational procedures may be included in this payload.\n\nAs part of the submit payload\n\n```\nconst payload = {\n user_identifier: '123',\n ...\n additional_custom_information: {\n customField1: 'Value 1',\n customField2: 'Value 2',\n // Add more custom fields as needed\n },\n};\n\nclickthrough.submit(payload).then(data => {\n\t// continue to submit the form\n})\n```\n\n### Styling Clickthrough Elements\n\nYou can utilize the class names provided by the Spotdraft Clickthrough SDK to style the items that the SDK renders. To make these elements match the appearance and feel of your application, you can apply unique CSS styles. The list of class names includes:\n\n- sd-clickthrough-checkbox: This class name can be used to target the checkbox element rendered by the SDK.\n\n- sd-clickthrough-text: This class name can be used to target the text content displayed in the Clickthrough agreement.\n\n### Event Handling\n\nYou can listen to events provided by the Spotdraft Clickthrough SDK in order to carry out particular tasks or react to user activities. To add event listeners to the SDK and record these events, use the 'on' method. Here's an example:\n\n```\nclickthrough.on(\"sdClickthroughLoaded\", function (data) {\n // Event listener callback function\n console.log(\"Clickthrough object loaded succesfully!!\");\n});\n```\n\nThe followings are the type of events you can listen to:\n\n- acceptanceToggled - When users checks/unchecks the checkbox.\n- sdClickthroughLoaded - When Spotdraft Clickthrough object successfully loads.\n- sdClickthroughLoadFailed - When Spotdraft Clickthrough object failed to load.\n\n### Full example\n\n```\n\n \n \n \n \n
\n \n \n
\n \n
\n \n \n\n\n```\n\n## Clickthrough KeyPointers\n\n### Generating Reports for Clickthrough Contracts\n\nYou have the option to create reports for Clickthrough contracts on SpotDraft using Key Pointers for each specific Clickthrough Packet. Before using this API, make sure to set up the necessary key pointers for your Clickthrough packet\n\n### Passing Data to Key Pointers\n\nTo send data from your website to a Clickthrough Packet's key pointer, use the `key_pointer_information` field in the clickthrough API payload. Data should be in key-value pairs. The values will be checked against their respective key pointer types for validation.\n\n### Validation and Display\n\nIf the validation fails, the key pointer values won't be shown in the key pointer section. However, this won't cause the contract generation to fail. You can find a list of key pointer values in the table below.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
KeyPointer TypesSyntaxSample
STRING“keypointer_field_name”: “Any_string_value”“slug_name”: \"Harvey Specter\"
DATE“keypointer_field_name”: “YYYY-MM-DD”

NB: Date should be in the aforementioned format as a string.		\"slug_dob\": \"2023-01-01\"
NUMBER“keypointer_field_name”: Integer\"slug_age\":24
CHECK BOX“keypointer_field_name”: bool“slug_is_admin”: true
CURRENCY“keypointer_field_name”:{ \"type\": \"Currency_type_code\", \"value\": Integer} \"slug_salary\": {\"type\": \"USD\", \"value\": 1000}
PHONE NUMBER“keypointer_field_name”:\n{\"number\": \"number_value\",\n\"country_code\": \"country_code_string\",\"code\": \"country_code_integer\"}\"slug_mobile\": {\"number\": \"9999912345\",\"country_code\": \"IN\",\"code\": \"+91\"}\n
DURATION“keypointer_field_name”: {\"days\": Integer, \"type\": \"DAY /WEEK / MONTH /YEARS\", \"value\": Integer}“slug_term”:\n{\"days\": 730, \"type\": \"YEARS\", \"value\": 2}\n
DROPDOWN“keypointer_field_name”: “value”

NB:Value should be in the dropdown list.		\"slug_country\": \"India\"\n
MULTI DROPDOWN“keypointer_field_name”: [“value1”, “value2”]

NB:Value1 and Value2 should be in the multi-dropdown list.		\"slug_multi\": [\"L1\",\"L2\"]\n
PARAGRAPHkeypointer_field_name”: “Any_string_values”“slug_paragraph: “It’s Paragraph KP”\n
\n\n## Clickthrough Agreement Reacceptance\n\nThe \"Clickthrough Re-Acceptance\" feature enables users to gather re-acceptance for the currently published version of the agreement. This allows users to obtain acceptance from individuals who have previously agreed to any earlier versions.\n\nUsers have the capability to specify whether a currently published version requires re-acceptance, both during the publishing process and after the current version is published. It's important to note that at any given time, only the latest published version can be designated for re-acceptance.\n\nOnce re-acceptance is collected, the SDK will provide users with information indicating whether a specific user has accepted the currently published version of the agreement. This information can be utilized to trigger a pop-up for re-acceptance or to notify users about modifications made to the prior agreement version.\n\nThe `isReacceptanceRequired` method of the SDK enables you to determine whether the current user needs to reaccept the updated agreement or not:\n\n```\nclickthrough.isReacceptanceRequired()\n .then(status) {\n // check if reaccapence is required or not\n if (status.trigger_acceptance) {\n // show the clickthrough elements\n // so users can reaccept the updated agreements\n clickthrough.init();\n }\n }\n```\n", "image": "/static/images/logo-blue.svg", "baseURL": "https://api.spotdraft.com/api", "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/spotdraft.com/main/v1", "version": "v1", "tags": [ "spotdraft.com", "main" ], "properties": [ { "type": "OpenAPI", "name": "OpenAPI definition", "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/spotdraft.com/main/v1/openapi.json", "mediaType": "application/openapi+json" }, { "type": "GitHubRepo", "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/spotdraft.com/main/v1" } ], "contact": [ { "FN": "help@spotdraft.com", "email": "help@spotdraft.com" } ] } ] }