{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"8e084d5b-2d4a-47d4-8c25-7b8e3e2e4dd1","name":"Hotsign API","description":"Welcome to hotsign's REST API. If you run into any issues or have any questions, please post a comment or email us [support@hotsign.com](mailto:support@hotsign.com).\n\n# Requirements\nThis documentation assumes that you're already familiar with REST API's and OAuth v2. Before you get started, you'll need the following:\n\n- A hotsign account. If you don't already have one, you can [create a free account](https://app.hotsign.com/#signup).\n- A `client_id` and `client_secret`. You can obtain a client id and secret by [registering a new app](https://app.hotsign.com/#account) in your hotsign account. If your using Postman for testing, make sure to supply `https://oauth.pstmn.io/v1/callback` as one of the callback URL's. You can change this later.\n- New accounts start with 10 invite credits. If you need more, email [support@hotsign.com](mailto:support@hotsign.com), tell us about your app, and we'll provide you with 100 invites.\n\n# Security & Best Practices\nHere are some best practices that you should follow when working with any API and sensitive data.\n\n| Data | Details |\n| -------- | ----------- |\n| HTTPS | hotsign only allows data to be transmitted over HTTPS. All HTTP requests and responses will be blocked. |\n| `client_secret` | **⚠️** Never make your client_secret public. This should only be sent directly to hotsign's API via your server. The client_secret should be treated as a password, do not store your client_secret in code but instead environment variables and encrypted if possible. |\n| `authorization_code` | Don't store authorization_codes as they are only temporary. They will expire within 15 seconds of creation. |\n| `token` | Tokens will expire within 1 hour. If you store them in your database, be sure to encrypt them. If a bad actor gets ahold of the token, they could access your clients' documents and invites using your registered app. |\n| `refresh_token` | Only store refresh token's if your app requires unattended access on behalf of your client. Refresh tokens will expire within 24 hours. If you do store the refresh_token, make sure to encrypt it. |\n| `state` | The state parameter serves as a CSRF protection mechanism if it contains a random value per request. When the user is redirected back to your app, double-check that the state value matches what you set it to originally. |\n\n# Setup\nOnce you have obtained the resources needed in the requirements section, you can begin making requests to the hotsign API. The first request will be to authenticate and retrieve a bearer token which will be used for subsequent requests.\n\nIf your using postman, the built-in Authorization has already been configured to use hotsign's OAuth v2. You will need to supply a `client_id` and `client_secret` in the environment variables.\n\n### Environment Variables\n| Variable | Details |\n| -------- | ------- |\n| `host` | Default `https://api.hotsign.com` |\n| `version` | Default `v1` |\n| `client_id` | Obtained in your hotsign account view. |\n| `client_secret` | Obtained in your hotsign account view. **⚠️** Never make your client_secret public. It should only be sent directly to hotsign's API via your server. The client_secret should be treated as a password, do not store your client_secret in code but rather environment variables and encrypted if possible. |\n| `client_redirect_uri` | This should be identical to one of the client redirect URLs provided when registering your application. |\n\nOnce you have configured your environment variables, open the **\"hotsign API\"** project settings, and at the bottom, click the **\"Get New Access Token\"** button. If you run into any errors, verify your environment variables and the your redirect_uri you provided when registering your app. Once you have successfully retrieved your bearer token, you can start marking request.\n\nTo obtain a token manually, you can follow the steps [documented here](#7457fc9f-4fee-4dce-abda-dbbf46b985c2).\n\n# Authentication\nThe hotsign API utilizes the OAuth v2 specification. Your clients' can authenticate with hotsign using Three-legged OAuth. We only allow Web-server apps. If you're building a client-side app, you'll have to set up a web server to act as the middle man for negotiating all requests between your app and the hotsign API.\n\n[Read more](#7457fc9f-4fee-4dce-abda-dbbf46b985c2)\n\n# Response Codes\n| Code | Description |\n| ---- | ----------- |\n| 200  | Success, JSON in response. |\n| 204  | Success, no content. |\n| 400  | Invalid request, the data you provided is likely invalid. |\n| 401  | Unauthorized, token or client_id and or secret are invalid. |\n| 402  | You ran out of invite credits and need to buy more. |\n| 404  | The resource you were looking for could not be found. |\n| 500  | Internal server error. Please report these to [support@hotsign.com](mailto:support@hotsign.com) |\n\n# Limits & Data Retention\n### Limits\n| Description | Limit |\n| ----------- | ----- |\n| Documents (aka templates) | 100 |\n| Max signers on a single document | 5 |\n| Webhook subscriptions | 25 |\n| Max content Size | 5MB |\n\n### Data Retention\n| Description | Data Retention |\n| ----------- | ----- |\n| Documents | After **120 days** of inactivity (the document hasn't been used or opened), the document will automatically be archived and scheduled for deletion within **10 days**. You can un-archive documents in the [Documents View](https://app.hotsign.com/#documents) |\n| Archived Documents | Documents that have been archived will remain archived for **10 days** and then be deleted. |\n| Invites | Invites are deleted after **45 days** of creation, whether or not they have been completed. Upon invite completion, the sender and all signers will be emailed a copy of the completed document along with the audit trail. |\n| Accounts | Will be removed after **6 months** of inactivity. The account holder will be notified before deletion. |\n| `authorization_code` | Authorization codes expire within 15 seconds of creation. |\n| `token` | Tokens expire in 1 hour. |\n| `refresh_token` | Refresh tokens expire in 24 hours. |\n\n# HTML & Markdown\nWhenever an invite is sent or document is saved, its content is sanitized. That means unsupported tags will be removed or converted.\n\n### Supported Tags\n| Description  | HTML Tag   | Markdown|\n|------------| ---------- | -------------------- |\n| **Bold**   | `<b>`      | `**bold**`           |\n| *Italic*   | `<i>`      | `*italic*`           |\n| Underline  | `<u>`      | `__underline__`      |\n| Paragraph  | `<p>`      ||\n| Line Break | `<br\\>`    | `\\r` or `\\n`         |\n| Header     | `<h2>`     | `#content#`          |\n| Ordered List | `<ol>`   ||\n| Unordered List | `<ul>` ||\n| List Element | `<li>`   ||\n\n### Converted Tags\n| From | To |\n|--------------|-----------------------|\n| `<em>` | `<i>` |\n| `<strong>` | `<b>` |\n| `<div>` | `<p>` |\n| `<h1>` | `<h2>` |\n| `<h3>` | `<h2>` |\n| `<h4>` | `<h2>` |\n| `<h5>` | `<h2>` |\n\n### HTML Field\nYou can add fields to your document using the HTML `<input>` tag along with the attributes documented below.\n\n| Attribute | Details |\n| ---------- |  ---------- |\n| `class` | Default `field`. Required or the input will be removed. |\n| `data-label` | String - Whenever the field is referenced, this label will be used. |\n| `data-required` | Boolean - Default `true` indicating whether or not the field is required. |\n| `data-signer` | Number - Default `1` used for assigning the field to a specific signer. |\n| `data-type` | String - The field can be one of the following types: `text`, `date`, `signature`, `email`, `phone`, `selection`. |\n| `data-options` | String - If \"selection\" was chosen for the **data-type** then you must supply a comma-separated string of options.|\n| `data-value` | If your sending an invite, you may optionally prefill the field with a data-value. Make sure the value is of the proper format. Signature fields cannot be prefilled. |\n\n### Accepted data-value's\n| Type   | Details |\n|--------------|-------------------------|\n| text | Any string |\n| email | A valid email address |\n| phone | A valid phone number |\n| selection | A string containing one of the options |\n\n### Markdown Field\nYou can add fields to your document using Markdown in any text editor. Fields are wrapped in `{...}`; options are separated by `/` and are in a specific order. The order is as follows: \n\nSigner / Label / Field Type / Prefill (only if sending)\n\nAn * just after the Label indicates whether or not the field is required.\n\n| Field Type   | Example                 |\n|--------------|-------------------------|\n| Text | `{1/Employee Name*/Text/John Smith}` |\n| Date | `{1/Effective Date*/Date/1-1-2021}` |\n| Signature | `{1/Employee Signature*/Signature}` |\n| Email | `{1/Employee Email*/Email/name@domain.com}` |\n| Phone | `{1/Employee Phone*/Phone/(123) 123-1234}` |\n| Selection | `{1/Gender*/Selection[Option 1,Option 2]/Option2}` |\n\n# Envelope Status\n| Status | Description |\n| ------ | ----------- |\n| `changedsigner` | The sender has changed the signer by updating the recipients email address. |\n| `scheduled` | The sender has scheduled the invite to be sent at a specific date and time. |\n| `sent` | The document was successfully sent. |\n| `bounced` | The invite email bounced. You can cancel the invite or change the signer. |\n| `spam` | The invite email to sign or complete the document was flagged as spam by the recipient. **⚠️** If your account receives too many spam complaints it may be suspended. |\n| `delivered` | The invite email was successfully delivered to the recipients inbox. |\n| `opened` | The recipient has opened the invite email. |\n| `viewed` | The recipient has viewed the document. |\n| `declined` | The recipient has declined to sign and or complete the document. |\n| `signed` | The recipient has successfully completed and or signed the document. |\n| `canceled` | The sender has canceled the invite. |\n| `expired` | The invitation has expired. It was neither completed or declined. |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"170781","team":1686133,"collectionId":"8e084d5b-2d4a-47d4-8c25-7b8e3e2e4dd1","publishedId":"TzCFirXV","public":true,"publicUrl":"https://developer.hotsign.com","privateUrl":"https://go.postman.co/documentation/170781-8e084d5b-2d4a-47d4-8c25-7b8e3e2e4dd1","customColor":{"top-bar":"FFFFFF","right-sidebar":"000000","highlight":"285FF6"},"documentationLayout":"classic-single-column","customisation":null,"version":"8.11.4","publishDate":"2021-03-24T08:06:58.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Hotsign Template Environment","id":"699badf8-c88b-4f4d-8099-540753240719","owner":"170781","values":[{"key":"host","value":"https://api.hotsign.com","enabled":true},{"key":"version","value":"v1","enabled":true},{"key":"client_id","value":"your-client-id","enabled":true},{"key":"client_secret","value":"your-client-secret","enabled":true},{"key":"client_redirect_uri","value":"your-redirect-url","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/6f692a44f91e69c139915b902861c110040daa5dcaceb82cf844d0e460f4c5da","favicon":"https://res.cloudinary.com/postman/image/upload/v1616626100/team/q6ado8m5tni4v7zizoqz.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Hotsign Template Environment","value":"170781-699badf8-c88b-4f4d-8099-540753240719"}],"canonicalUrl":"https://developer.hotsign.com/view/metadata/TzCFirXV"}