{"openapi":"3.1.0","info":{"title":"DocSpring API","version":"v2","description":"Use DocSpring's API to programmatically fill out PDF forms, convert HTML to PDFs, merge PDFs, or request legally binding e-signatures."},"servers":[{"url":"https://sync.api.docspring.com/api/v2","description":"US region"},{"url":"https://sync.api-eu.docspring.com/api/v2","description":"EU region"}],"security":[{"api_token_basic":[]}],"components":{"securitySchemes":{"api_token_basic":{"type":"http","scheme":"basic","description":"Username: API Token ID, Password: API Token Secret"}},"schemas":{"AuthenticationCheck":{"title":"AuthenticationCheck","type":"object","description":"Returned when the Authorization header has a valid API token.","required":["authenticated"],"properties":{"authenticated":{"type":"boolean","description":"Always true."}},"additionalProperties":true},"CombinedPdf":{"title":"CombinedPdf","type":"object","description":"A PDF made by merging other PDFs: submissions, other combined PDFs, templates, custom files and PDFs from URLs.","required":["id","state","source_pdfs","metadata","has_password","delete_custom_files","error_message","files","actions","expired","expires_at","processed_at","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The combined PDF's ID."},"state":{"type":"string","title":"CombinedPdfState","x-type-description":"Where a combined PDF is in its processing.","x-extensible-enum":["pending","processed","error","insufficient_credits","account_suspended"],"description":"`pending` until the PDF has been generated, then `processed`. `insufficient_credits`: waiting for credits; `error_message` says whether the PDF is generated once you add them. `account_suspended`: waiting for the account to be reactivated, for up to 30 days. `error`: the PDFs couldn't be merged (see `error_message`). Waiting ends in `error` if it's discarded or takes over 30 days."},"source_pdfs":{"type":"array","minItems":1,"description":"The PDFs to merge, in order.","items":{"title":"CombinedPdfSource","type":"object","required":["type"],"properties":{"type":{"title":"CombinedPdfSourceType","type":"string","x-extensible-enum":["submission","combined_pdf","template","custom_file","url"],"description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","x-type-description":"What a source PDF is."},"id":{"type":"string","minLength":1,"description":"The ID of the submission, combined PDF, template or custom file."},"url":{"type":"string","format":"uri","description":"For a `url` source, the URL to download the PDF from. Removed once the combined PDF has expired."},"template_version":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","description":"For a `template` source, the version to use: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published).","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"processed":{"type":"boolean","description":"For a `template` source: true (the default) merges the template's processed PDF, which is the PDF submissions are filled in on (decrypted, with its form fields removed). false merges the PDF as it was uploaded."}},"x-type-description":"A PDF to merge.","additionalProperties":false}},"metadata":{"type":"object","description":"Your own data about the combined PDF, such as an ID from your app."},"has_password":{"type":"boolean","description":"Whether the PDF needs a password to open (`password`)."},"delete_custom_files":{"type":"boolean","description":"Delete the custom files in `source_pdfs` once the combined PDF has been generated (they're kept if it fails). Other combined PDFs can't use them after that. A test API token can't delete custom files."},"error_message":{"type":["string","null"],"description":"Why the PDFs couldn't be merged, when `state` is `error`."},"files":{"$ref":"#/components/schemas/CombinedPdfFiles","description":"The generated files, by format. Empty until the PDF has been generated, and once it has expired."},"actions":{"type":"array","description":"The uploads of the PDF to your storage (account integrations).","items":{"$ref":"#/components/schemas/SubmissionAction"}},"expired":{"type":"boolean","description":"An expired combined PDF's PDF, metadata, password and source URLs have been deleted."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the combined PDF expires (`expires_in` after it's generated). Null if it's kept until you delete it."},"processed_at":{"type":["string","null"],"format":"date-time","description":"When the PDF was generated. Null until then."},"created_at":{"type":"string","format":"date-time","description":"When the combined PDF was created."},"updated_at":{"type":"string","format":"date-time","description":"When the combined PDF was last updated."}},"additionalProperties":true},"CombinedPdfList":{"title":"CombinedPdfList","type":"object","description":"A page of combined PDFs, newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/CombinedPdf"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"CustomFile":{"title":"CustomFile","type":"object","description":"A PDF you uploaded to merge with other PDFs (POST /combined_pdfs). Get an upload URL with GET /uploads/presign first.","required":["id","download_url","size","content_type","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The custom file's ID."},"download_url":{"type":["string","null"],"format":"uri","description":"A temporary link to download the file."},"size":{"type":["integer","null"],"description":"The file's size in bytes."},"content_type":{"type":["string","null"],"description":"The file's media type, such as `application/pdf`."},"created_at":{"type":"string","format":"date-time","description":"When the custom file was created."},"updated_at":{"type":"string","format":"date-time","description":"When the custom file was last updated."}},"additionalProperties":true},"CustomFileList":{"title":"CustomFileList","type":"object","description":"A page of custom files, newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/CustomFile"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"The body of every error response.","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":true},"ErrorInfo":{"title":"ErrorInfo","type":"object","description":"What went wrong.","required":["code","message","details","request_id"],"properties":{"code":{"type":"string","description":"A machine-readable error code. Clients should handle codes they don't know: new codes can be added. `invalid_data`: a submission's data doesn't match its template's fields. The submission is still recorded. `insufficient_credits` (402): your credit balance can't cover a live PDF. The record was saved and waits for credits in the `insufficient_credits` state: its ID is in `submission_id`, `submission_batch_id` or `combined_pdf_id`. `upgrade_required` (403): your plan doesn't include this, such as more templates or the embedded template editor. `account_suspended` (403): the account is suspended, so it can't create submissions. `polling_timeout`: on a sync.api host, the PDF wasn't ready in time. The record was created and is still being processed: its ID is in `submission_id`, `submission_batch_id`, `combined_pdf_id` or `template_id`. Without one of these IDs, the request itself got no answer in time, and the record may or may not have been created.","title":"ErrorCode","x-type-description":"A machine-readable error code. New codes can be added.","x-extensible-enum":["invalid_request","unauthorized","payment_required","insufficient_credits","forbidden","upgrade_required","account_suspended","not_found","method_not_allowed","conflict","gone","request_too_large","unsupported_media_type","validation_failed","invalid_data","rate_limited","internal_error","bad_gateway","service_unavailable","upstream_timeout","polling_timeout"]},"message":{"type":"string","description":"A human-readable explanation, safe to show to developers."},"details":{"type":"array","description":"What was wrong with each part of the request. Empty when the error isn't about one part of it.","items":{"$ref":"#/components/schemas/ErrorDetail"}},"request_id":{"type":["string","null"],"description":"The ID of the request. Include it when you contact support."},"submission_id":{"type":"string","description":"When a submission's data fails validation, the submission is still recorded (state `invalid_data`) so you can see it in the dashboard. This is its ID. With `insufficient_credits`, the submission that waits for credits. With `polling_timeout`, the submission that's still being processed."},"submission_batch_id":{"type":"string","description":"The ID of the recorded batch, when items in a batch fail validation. With `insufficient_credits`, the batch whose submissions wait for credits. With `polling_timeout`, the batch that's still being processed."},"combined_pdf_id":{"type":"string","description":"With `insufficient_credits`, the combined PDF that waits for credits. With `polling_timeout`, the combined PDF that's still being processed."},"template_id":{"type":"string","description":"With `polling_timeout`, the template whose PDF is still being processed."}},"additionalProperties":true},"ErrorDetail":{"title":"ErrorDetail","type":"object","description":"One problem with the request, such as a missing or invalid property.","required":["code","message"],"properties":{"code":{"type":"string","description":"What's wrong: `required`, `unknown_property`, `type`, `enum`, `format`, a JSON Schema keyword such as `minLength`, or a DocSpring code. New codes can be added."},"message":{"type":"string","description":"A human-readable explanation of the problem."},"pointer":{"type":"string","description":"A JSON pointer to the value in the request body (RFC 6901). An empty string means the whole body. In a submission's `data_errors`, it points into the request that created the submission."},"parameter":{"type":"string","description":"The query parameter the detail is about."},"submission_id":{"type":"string","description":"For a batch item that failed validation, the ID of the submission recorded for it."}},"additionalProperties":true},"Folder":{"title":"Folder","type":"object","description":"A folder of templates. Folders can contain other folders.","required":["id","name","path","parent_folder_id","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The folder's ID."},"name":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/]*$","description":"The folder's name. It can't contain `/`, and is unique within its parent folder.","x-pattern-message":"can't contain a slash (/)"},"path":{"type":"string","description":"The path of the folder this folder is in, such as `/Contracts`. `/` for a folder at the root."},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder this folder is in. Null for a folder at the root."},"created_at":{"type":"string","format":"date-time","description":"When the folder was created."},"updated_at":{"type":"string","format":"date-time","description":"When the folder was last updated."}},"additionalProperties":true},"FolderList":{"title":"FolderList","type":"object","description":"A page of folders, newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/Folder"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"GeneratedFile":{"title":"GeneratedFile","type":"object","description":"A file that DocSpring generated, such as a submission's PDF. A file made after its submission was processed is listed while it's being made: check its `state` before using its links.","required":["state","error_message","download_url","permanent_url","filename","content_type","size","sha256"],"properties":{"state":{"type":"string","title":"GeneratedFileState","x-extensible-enum":["pending","processed","error"],"x-type-description":"Whether a generated file has been made.","description":"`processed` once the file has been made. `pending` while it's being made, and `error` if it couldn't be made (see `error_message`)."},"error_message":{"type":["string","null"],"description":"Why the file couldn't be made, when `state` is `error`."},"download_url":{"type":["string","null"],"format":"uri","description":"A temporary link to download the file. Null until the file has been made, and when your account turns off download links for submissions."},"permanent_url":{"type":["string","null"],"format":"uri","description":"A link to download the file that doesn't expire: it redirects to a new temporary link. It needs your API token or a signed-in session, except for a submission of a template that makes its submissions public. Null until the file has been made."},"filename":{"type":"string","description":"The file's name, such as `sub_123.pdf`."},"content_type":{"type":"string","description":"The file's media type, such as `application/pdf`."},"size":{"type":["integer","null"],"description":"The file's size in bytes. Null until the file has been made."},"sha256":{"type":["string","null"],"description":"The SHA-256 hash of the file. Null until the file has been made."}},"additionalProperties":true},"SubmissionFiles":{"title":"SubmissionFiles","type":"object","description":"A submission's generated files. Each one is left out until it exists.","properties":{"pdf":{"$ref":"#/components/schemas/GeneratedFile","description":"The submission's PDF."},"audit_trail":{"$ref":"#/components/schemas/GeneratedFile","description":"The audit trail of a submission with signature requests: who signed, when and how. It's also added to the end of the PDF when the template's `merge_audit_trail_pdf` is on."},"preview":{"$ref":"#/components/schemas/GeneratedFile","description":"The preview PDF from POST /submissions/{submission_id}/generate_preview, such as for a submission still waiting for its signature requests."}},"additionalProperties":true},"CombinedPdfFiles":{"title":"CombinedPdfFiles","type":"object","description":"A combined PDF's generated files, by format.","properties":{"pdf":{"$ref":"#/components/schemas/GeneratedFile"}},"additionalProperties":true},"SignatureRequest":{"title":"SignatureRequest","type":"object","description":"A request for someone to fill in their fields of a submission and sign it. Someone who only fills in fields for the people who sign later (such as an employer's section) has a signature request too. The submission's PDF is generated once every signature request is completed.","required":["id","submission_id","name","email","fields","metadata","role","sort_order","state","data","viewed_at","completed_at","declined_at","auth_type","auth_second_factor_type","auth_provider","auth_session_started_at","auth_session_id_hash","auth_user_id_hash","auth_username_hash","auth_phone_number_hash","ip_address","user_agent","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The signature request's ID."},"submission_id":{"type":"string","description":"The ID of the submission the signature request belongs to."},"name":{"type":["string","null"],"maxLength":255,"description":"The name of the person the request is for."},"email":{"type":["string","null"],"maxLength":255,"description":"Their email address."},"fields":{"type":["array","null"],"description":"The fields this person fills in. Null for a signature request created with API v1 without a field list: it asks for every field the submission's data doesn't have.","items":{"type":"string","minLength":1}},"metadata":{"type":"object","description":"Your own data about the signature request, such as an ID from your app."},"role":{"type":"string","minLength":1,"description":"Which of the template's signers the person is. Until templates have roles of their own, a template's signers are `Signer 1`, `Signer 2` and so on, up to `Signer 100`: `Signer 1` is the one whose details the template's `@@signature_requests/0` fields print."},"sort_order":{"type":"integer","description":"The signer's position, from 0: `Signer 1` is 0. The template's `@@signature_requests/<sort_order>` fields print this signature request's details."},"state":{"type":"string","title":"SignatureRequestState","x-type-description":"Whether a signature request is waiting for its signer, completed or declined.","x-extensible-enum":["pending","completed","declined"],"description":"`pending` until the person completes the signature request (`completed`) or declines it (`declined`)."},"data":{"type":["object","null"],"description":"The values this person entered for their own fields (`fields`). Null when their submission's data is left out: in lists without `include_data=true`, in the events of a webhook that leaves out submission data, and once the submission has expired."},"viewed_at":{"type":["string","null"],"format":"date-time","description":"When the person first opened the signature request."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When they completed it."},"declined_at":{"type":["string","null"],"format":"date-time","description":"When they declined it."},"auth_type":{"title":"SignatureRequestAuthType","type":"string","x-extensible-enum":["none","password","oauth","email_link","phone_number","ldap","saml"],"description":"How your app authenticated the person before it showed them the signature request.","x-type-description":"How your app authenticated a person before it showed them a signature request."},"auth_second_factor_type":{"title":"SignatureRequestAuthSecondFactorType","type":"string","x-extensible-enum":["none","phone_number","totp","mobile_push","security_key","fingerprint"],"description":"The second factor your app authenticated them with, if any.","x-type-description":"A second factor your app authenticated a person with."},"auth_provider":{"type":["string","null"],"maxLength":255,"description":"The service that authenticated them, such as `google`. Required when `auth_type` is `oauth`."},"auth_session_started_at":{"type":["string","null"],"format":"date-time","description":"When your app authenticated them. Set for you with `email_link`."},"auth_session_id_hash":{"type":["string","null"],"description":"A hash of your app's session ID, for the audit trail."},"auth_user_id_hash":{"type":["string","null"],"description":"Their user ID in your app, or a SHA-256 hash of a salt and the user ID."},"auth_username_hash":{"type":["string","null"],"description":"Their username in your app, or a SHA-256 hash of a salt and the username."},"auth_phone_number_hash":{"type":["string","null"],"description":"The phone number they authenticated with, or a SHA-256 hash of a salt and the phone number."},"ip_address":{"type":["string","null"],"description":"The IP address they completed the signature request from. Null in the events of a webhook that leaves out submission data."},"user_agent":{"type":["string","null"],"description":"The User-Agent header of the browser they completed the signature request with. Null in the events of a webhook that leaves out submission data."},"created_at":{"type":"string","format":"date-time","description":"When the signature request was created."},"updated_at":{"type":"string","format":"date-time","description":"When the signature request was last updated."}},"additionalProperties":true},"SignatureRequestToken":{"title":"SignatureRequestToken","type":"object","description":"A token that opens a signature request without signing in to DocSpring, in a form embedded in your app or from a link you send. Create a token each time you open the form or send a link, rather than storing one to reuse later: its link expires. A signing page that opened before then keeps working for 7 more days, so the person can finish the form later.","required":["id","signature_request_id","type","secret","signature_request_url","expires_at","created_at"],"properties":{"id":{"type":"string","description":"The token's ID."},"signature_request_id":{"type":"string","description":"The ID of the signature request the token opens."},"type":{"title":"SignatureRequestTokenType","type":"string","x-type-description":"How long a signature request token's link opens the signature request.","x-extensible-enum":["api","email"],"description":"`api`: the link opens the signature request for 24 hours. `email`: 7 days."},"secret":{"type":"string","description":"The token's secret. It's only returned when the token is created."},"signature_request_url":{"type":"string","description":"A link that opens the signature request with this token."},"expires_at":{"type":"string","format":"date-time","description":"When the link stops opening the signature request."},"created_at":{"type":"string","format":"date-time","description":"When the token was created."}},"additionalProperties":true},"SignatureRequestEvent":{"title":"SignatureRequestEvent","type":"object","description":"Something that happened to a signature request outside DocSpring, for its audit trail: you sent the request to the person (`send_request`). The audit trail shows it as reported by your account.","required":["id","submission_id","signature_request_id","event_type","message_type","message_recipient","occurred_at","created_at"],"properties":{"id":{"type":"string","description":"The event's ID."},"submission_id":{"type":"string","description":"The ID of the signature request's submission."},"signature_request_id":{"type":"string","description":"The ID of the signature request."},"event_type":{"type":"string","title":"SignatureRequestEventType","x-type-description":"Something that happened to a signature request.","x-extensible-enum":["send_request","view_request","accepted_terms","decline_request","sign_request","all_completed"],"description":"What happened."},"message_type":{"title":"SignatureRequestMessageType","type":["string","null"],"x-extensible-enum":["email","sms","fax","mail","slack","msteams","discord","telegram","whatsapp"],"description":"How you sent the request. Required for `send_request`.","x-type-description":"How a signature request was sent to a person."},"message_recipient":{"type":["string","null"],"maxLength":255,"description":"Where you sent the request, such as an email address or a phone number. Required for `send_request`."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened. Default now."},"created_at":{"type":"string","format":"date-time","description":"When the event was recorded."}},"additionalProperties":true},"SubmissionBatch":{"title":"SubmissionBatch","type":"object","description":"Submissions created together in one request. Their PDFs are only generated when every submission in the batch is valid.","required":["id","state","metadata","total_count","pending_count","error_count","completion_percentage","submissions","processed_at","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The batch's ID."},"state":{"type":"string","title":"SubmissionBatchState","x-type-description":"Where a submission batch is in its processing.","x-extensible-enum":["pending","processed","error"],"description":"`pending` while the PDFs are being generated, then `processed`. `error` as soon as a submission fails, while the others can still be pending: the batch has finished once `processed_at` is set."},"metadata":{"type":"object","description":"Your own data about the batch, such as an ID from your app."},"total_count":{"type":"integer","description":"The number of submissions in the request."},"pending_count":{"type":"integer","description":"The submissions whose PDFs haven't been generated yet."},"error_count":{"type":"integer","description":"The submissions that were invalid or whose PDFs couldn't be generated."},"completion_percentage":{"type":"integer","description":"The percentage of the batch's submissions that have finished, from 0 to 100."},"submissions":{"type":"array","description":"The batch's submissions, in the order of the request. Their `data` is null unless you pass `include_data=true`. A batch that failed validation only has the submissions that were recorded as `invalid_data`.","items":{"$ref":"#/components/schemas/Submission"}},"processed_at":{"type":["string","null"],"format":"date-time","description":"When every submission had finished."},"created_at":{"type":"string","format":"date-time","description":"When the batch was created."},"updated_at":{"type":"string","format":"date-time","description":"When the batch was last updated."}},"additionalProperties":true},"Submission":{"title":"Submission","type":"object","description":"Data submitted to a template, and the PDF generated from it.","required":["id","template_id","template_type","template_version","batch_id","source","state","test","editable","data","data_errors","error_message","metadata","has_password","signature_requests","actions","truncated_text","files","preview_generated_at","expired","expires_at","processed_at","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The submission's ID."},"template_id":{"type":["string","null"],"description":"Null once the template has been permanently deleted."},"template_type":{"title":"TemplateType","type":"string","x-extensible-enum":["pdf","html"],"description":"The template's type: `pdf` or `html`.","x-type-description":"The kind of template: `pdf` (fields placed on an uploaded PDF) or `html` (a PDF rendered from HTML)."},"template_version":{"type":["string","null"],"description":"The published version of the template the submission used. Null for the draft."},"batch_id":{"type":["string","null"],"description":"The ID of the batch the submission was created in."},"source":{"type":"string","title":"SubmissionSource","x-type-description":"What created a submission.","x-extensible-enum":["api","web","reprocess","webhook"],"description":"`api`: created with the API. `web`: a web form. `reprocess`: a copy of another submission, made to generate its PDF again."},"state":{"type":"string","title":"SubmissionState","x-type-description":"Where a submission is in its processing.","x-extensible-enum":["pending","processed","invalid_data","error","image_download_failed","image_processing_failed","waiting_for_signature_requests","syntax_error","insufficient_credits","account_suspended","license_revoked","accidental","declined"],"description":"`pending` until the PDF has been generated, then `processed`. `waiting_for_signature_requests` until every signature request is completed. `insufficient_credits`: waiting for credits; `error_message` says whether the PDF is generated once you add them. `account_suspended`: waiting for the account to be reactivated, for up to 30 days. Waiting ends in `error` if it's discarded or takes over 30 days. Every other state is final, with no PDF: `invalid_data` (the data doesn't match the template's fields: see `data_errors`), `declined` (a signature request was declined), and the states where generating the PDF failed, which have an `error_message`: `syntax_error` (a mistake in an HTML template's Liquid or SCSS), `image_download_failed` or `image_processing_failed` (an image in the data or the template couldn't be downloaded or read) and `error` (anything else). Older submissions can also be `license_revoked` or `accidental`."},"test":{"type":"boolean","description":"Test PDFs have a watermark and are free. Live PDFs use credits. Submissions made with a test API token are always test submissions."},"editable":{"type":"boolean","description":"`true` keeps the PDF's text and check fields fillable, and `false` flattens every field. Left out, the template decides: its `editable_submissions` setting, or each field's own Editable option. A response shows the template's setting when the request left this out. Can't be `true` with `signature_requests`."},"data":{"type":["object","null"],"description":"The submission's data, with the values entered in completed signature requests. Lists leave it out (null) unless you pass `include_data=true`. Empty once the submission has expired."},"data_errors":{"type":"array","description":"Why the data doesn't match the template's fields, when `state` is `invalid_data`: the same details as the 422 response that recorded it, with pointers into the request that created the submission (`/data/name`). Cleared once the submission has expired.","items":{"$ref":"#/components/schemas/ErrorDetail"}},"error_message":{"type":["string","null"],"description":"Why the PDF couldn't be generated, when `state` is `error`."},"metadata":{"type":"object","description":"Your own data about the submission, such as an ID from your app. It isn't printed on the PDF."},"has_password":{"type":"boolean","description":"Whether the PDF needs a password to open (`password`)."},"signature_requests":{"type":"array","items":{"$ref":"#/components/schemas/SignatureRequest"},"description":"The people asked to sign the submission (and fill in their fields), in order."},"actions":{"type":"array","description":"The uploads of the submission's PDF to your storage (account integrations).","items":{"$ref":"#/components/schemas/SubmissionAction"}},"truncated_text":{"type":["object","null"],"description":"The text of each field that didn't fit in it, by field name. Left out (null) with `data`, and empty once the submission has expired.","additionalProperties":{"type":"array","items":{"type":"string"}}},"files":{"$ref":"#/components/schemas/SubmissionFiles","description":"The generated files: `pdf` once the submission has been processed, `audit_trail` once its signature requests are completed, and `preview` once a preview PDF has been generated. Empty once the submission has expired."},"preview_generated_at":{"type":["string","null"],"format":"date-time","description":"When the preview PDF was generated. Null if there is no preview."},"expired":{"type":"boolean","description":"An expired submission's data, metadata, password and PDF have been deleted."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the submission expires. Null if it's kept until you delete it."},"processed_at":{"type":["string","null"],"format":"date-time","description":"When the PDF was generated. Null until then."},"created_at":{"type":"string","format":"date-time","description":"When the submission was created."},"updated_at":{"type":"string","format":"date-time","description":"When the submission was last updated."}},"additionalProperties":true},"SubmissionList":{"title":"SubmissionList","type":"object","description":"A page of submissions, newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/Submission"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"SubmissionAction":{"title":"SubmissionAction","type":"object","description":"An upload of a PDF to your storage, such as an S3 bucket.","required":["id","integration_id","state","action_type","result_data","error_message"],"properties":{"id":{"type":"string","description":"The upload's ID."},"integration_id":{"type":["string","null"],"description":"The ID of the account integration it used."},"state":{"type":"string","title":"SubmissionActionState","x-type-description":"Where a submission action (an upload to your storage) is.","x-extensible-enum":["pending","processed","failed","error"],"description":"`pending` until the upload has run, then `processed`. `failed`: your storage rejected it. `error`: it failed in DocSpring."},"action_type":{"type":"string","title":"SubmissionActionType","x-type-description":"The kind of storage a submission action uploads the PDF to.","x-extensible-enum":["webhook","slack_webhook","email","aws_s3_upload","dropbox_upload","google_drive_upload","box_upload"],"description":"The kind of storage, such as `aws_s3_upload` for an S3 bucket."},"result_data":{"type":"object","description":"Where the PDF was uploaded, such as the S3 bucket and key."},"error_message":{"type":["string","null"],"description":"Why the upload failed, when `state` is `failed` or `error`."}},"additionalProperties":true},"FieldOverride":{"title":"FieldOverride","type":"object","writeOnly":true,"description":"Changes to one field's settings for this submission only. Settings left out keep the template's.","properties":{"static":{"type":"boolean","description":"Print the field's `default` (a fixed value, or a formula for a number field) on the PDF instead of a value from `data`."},"editable":{"type":"boolean","description":"Keep this field fillable in the PDF instead of flattening it to text. The submission's `editable` overrides it."},"default":{"type":["string","null"],"description":"The value used when `data` has none for the field."},"title":{"type":"string","description":"The field's label on the signing form."},"required":{"type":"boolean","description":"Whether `data` must have a value for the field."},"option_list":{"type":["string","null"],"description":"The values the field can take, separated by commas, such as `Yes,No`. Null allows any value."},"combined_field_names":{"type":"string","description":"The names of the fields a combined field joins, separated by commas."},"combined_field_type":{"type":"string","enum":["separator","format"],"description":"How a combined field joins its fields' values.","title":"CombinedFieldType","x-type-description":"How a combined field joins its fields' values: with `combined_field_separator` between them (`separator`), or into `combined_field_format` (`format`)."},"combined_field_separator":{"type":"string","description":"The text between the values of a combined field, such as `, `."},"combined_field_format":{"type":"string","description":"The text a combined field prints, with `$0`, `$1` and so on for its fields' values, such as `$0, $1`."},"integer":{"type":"boolean","description":"Whether a number field takes only whole numbers."},"include_time":{"type":["boolean","null"],"description":"Whether a date field takes a date and time (RFC 3339) rather than a date (YYYY-MM-DD)."},"signature_allow_draw":{"type":"boolean","description":"Let the person draw their signature or initials on the signing form."},"signature_allow_type":{"type":"boolean","description":"Let the person type their signature or initials on the signing form."},"barcode_symbology":{"type":"string","enum":["code_25","code_39","code_93","code_128","ean_13","ean_8","upc_a","pdf417"],"description":"The kind of barcode a field with display_type `barcode` prints.","title":"BarcodeSymbology","x-type-description":"A kind of barcode."},"hidden":{"type":"boolean","description":"Leave the field off the PDF. Its value is still in the data, and combined fields can use it."},"x":{"type":"number","minimum":0,"description":"The distance from the left edge of the page, in the template editor's page units."},"y":{"type":"number","minimum":0,"description":"The distance from the top of the page, in the template editor's page units."},"width":{"type":"number","exclusiveMinimum":0,"description":"The field's width, in the template editor's page units."},"height":{"type":"number","exclusiveMinimum":0,"description":"The field's height, in the template editor's page units."},"rotation":{"type":"number","minimum":-360,"maximum":360,"description":"The field's rotation in degrees, clockwise."},"display_type":{"type":"string","enum":["text","check","qrcode","barcode","image","shape"],"description":"How the field's value is drawn on the PDF.","title":"FieldDisplayType","x-type-description":"How a field's value is drawn on the PDF: as text, a check mark, a QR code, a barcode, an image or a shape."},"opacity":{"type":"number","minimum":0,"maximum":1,"description":"The field's opacity, from 0 (invisible) to 1 (solid)."},"date_time_format":{"type":["string","null"],"description":"How a date field's value is printed, as a strftime format such as `%m/%d/%Y`. Null uses the template's date format."},"typeface":{"type":["string","null"],"enum":["Inconsolata","Roboto Mono","Ubuntu Mono","Menlo","Courier","Helvetica","Arial","Calibri","Open Sans","Roboto","Lato","Poppins","Public Sans","Questrial","Times New Roman","Dancing Script","Lovtony Script",null],"description":"The font of the field's text. Null uses the template's default.","title":"Typeface","x-type-description":"One of the template editor's typefaces."},"font_size":{"type":["integer","null"],"minimum":1,"description":"The font size in points, a whole number. Null uses the template's default."},"character_spacing":{"type":"number","minimum":0,"maximum":50,"description":"Extra space between characters, in points (0 to 50)."},"bold":{"type":"boolean","description":"Print the text in bold."},"uppercase":{"type":"boolean","description":"Print the text in capitals."},"strikethrough":{"type":"boolean","description":"Strike through the text."},"keep_leading_spaces":{"type":"boolean","description":"Keep the spaces at the start of the text and of each line, so you can line text up with spaces."},"overflow":{"type":"string","enum":["shrink_to_fit","truncate"],"description":"What happens to text that doesn't fit in the field.","title":"TextOverflow","x-type-description":"What happens to text that doesn't fit in its field."},"multiline":{"type":"boolean","description":"Wrap the text over several lines when it doesn't fit on one."},"multiline_lines":{"type":["integer","null"],"minimum":1,"maximum":300,"description":"The number of lines in a multiline field, for a PDF with ruled lines. Null for no fixed number of lines."},"max_length":{"type":["integer","null"],"minimum":0,"description":"The most characters the field takes. Null for no limit."},"color":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{6}$","description":"The text color, as 6 hex digits without `#`, such as `444444`. Null uses the template's default.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"background_color":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{6}$","description":"The field's background color, as 6 hex digits without `#`. Null for none.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"alignment":{"type":"string","enum":["left","center","right","justify"],"description":"How text is aligned in its field. `justify` lines up both edges of every line of multiline text except the last of each paragraph.","title":"TextAlignment","x-type-description":"A horizontal text alignment."},"v_alignment":{"type":"string","enum":["bottom","center","top"],"description":"How text is aligned vertically in its field.","title":"TextVerticalAlignment","x-type-description":"A vertical text alignment."},"comb":{"type":"boolean","description":"Print one character in each of the field's equally spaced boxes (combs)."},"comb_number_of_cells":{"type":"integer","minimum":1,"description":"The number of boxes in a comb field."},"comb_value_offset":{"type":"integer","minimum":0,"description":"The character of the value that the first box starts from, for a value split over several comb fields (such as the parts of a Social Security number)."},"shape_type":{"type":"string","enum":["square","rectangle","circle","ellipse","triangle","polygon"],"description":"The shape a field with display_type `shape` draws.","title":"ShapeType","x-type-description":"A shape a field can draw."},"shape_sides":{"type":"integer","minimum":3,"maximum":12,"description":"The number of sides of a `polygon` shape."},"shape_border_width":{"type":"integer","minimum":1,"description":"The width of a shape's border, in points, a whole number."},"shape_border_color":{"type":"string","pattern":"^[A-Fa-f0-9]{6}$","description":"The color of a shape's border, as 6 hex digits without `#`.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"shape_fill_color":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{6}$","description":"The color a shape is filled with, as 6 hex digits without `#`. Null for no fill.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"check_character":{"type":"string","enum":["&#10003;","&#10004;","&#10006;","&#10007;","&#10008;"],"description":"The character that a ticked check box prints.","title":"CheckCharacter","x-type-description":"A check mark or cross, as the HTML entity of its character: ✓ (`&#10003;`), ✔ (`&#10004;`), ✖ (`&#10006;`), ✗ (`&#10007;`) or ✘ (`&#10008;`).","x-enum-varnames":["CHECK","HEAVY_CHECK","MULTIPLICATION_X","BALLOT_X","HEAVY_BALLOT_X"]},"check_color":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{6}$","description":"The color of the check mark, as 6 hex digits without `#`. Null uses the template's default.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"qrcode_color":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{6}$","description":"The color of a QR code, as 6 hex digits without `#`. Null for black.","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"true_text":{"type":["string","null"],"description":"What a boolean field with display_type `text` prints for `true`."},"false_text":{"type":["string","null"],"description":"What a boolean field with display_type `text` prints for `false`."},"condition":{"type":["string","null"],"description":"The value a check mark or shape is drawn for: it's drawn when the field's value matches, as `string_condition_type` or `number_condition_type` says."},"string_condition_type":{"type":"string","enum":["equals","contains","starts_with","ends_with","regex"],"description":"How a string field's value is compared with `condition`.","title":"StringConditionType","x-type-description":"How a string field's value is compared with a check mark's or shape's condition."},"number_condition_type":{"type":"string","enum":["equals","range","gte","gt","lte","lt"],"description":"How a number field's value is compared with `condition`, or with `number_condition_range_min` and `number_condition_range_max` for `range`.","title":"NumberConditionType","x-type-description":"How a number field's value is compared with a check mark's or shape's condition."},"number_condition_range_min":{"type":["number","null"],"description":"The lower end of a `range` condition."},"number_condition_range_max":{"type":["number","null"],"description":"The upper end of a `range` condition."},"number_condition_range_exclusive_min":{"type":"boolean","description":"Leave the lower end itself out of a `range` condition."},"number_condition_range_exclusive_max":{"type":"boolean","description":"Leave the upper end itself out of a `range` condition."},"invert_boolean_condition":{"type":"boolean","description":"Draw a boolean field's check mark or shape for `false` instead of `true`."},"decimal_places":{"type":["integer","null"],"minimum":0,"maximum":99,"description":"The number of decimal places a number field prints. Null prints the value as it was sent."},"image_scale_type":{"type":"string","enum":["fit","fill","stretch"],"description":"How an image is resized to its field.","title":"ImageScaleType","x-type-description":"How an image is resized to its field: scaled to fit inside it (`fit`), scaled to cover it and cropped (`fill`), or stretched to its shape (`stretch`)."},"image_gravity":{"type":"string","enum":["NorthWest","North","NorthEast","West","Center","East","SouthWest","South","SouthEast"],"description":"Where an image sits in its field when it doesn't fill it, or which part is kept when it's cropped.","title":"ImageGravity","x-type-description":"A position inside a field, such as `NorthWest` for the top left corner."}},"x-unknown-property-message":"isn't a field setting","x-not-allowed-properties":{"id":"can't be changed for one submission. Change the field in the template","name":"can't be changed for one submission. Change the field in the template","type":"can't be changed for one submission. Change the field in the template","field_count":"can't be changed for one submission. Change the field in the template","fieldCount":"can't be changed for one submission. Change the field in the template","dependencies":"can't be changed for one submission. Change the field in the template","acroform_name":"can't be changed for one submission. Change the field in the template","allow_additional_items":"can't be changed for one submission. Change the field in the template","allowAdditionalItems":"can't be changed for one submission. Change the field in the template","min_items":"can't be changed for one submission. Change the field in the template","minItems":"can't be changed for one submission. Change the field in the template","max_items":"can't be changed for one submission. Change the field in the template","maxItems":"can't be changed for one submission. Change the field in the template","description":"can't be changed for one submission: the template's setting always applies. Change it in the template","placeholder":"can't be changed for one submission: the template's setting always applies. Change it in the template","metadata":"can't be changed for one submission: the template's setting always applies. Change it in the template","minimum":"can't be changed for one submission: the template's setting always applies. Change it in the template","maximum":"can't be changed for one submission: the template's setting always applies. Change it in the template","exclusive_minimum":"can't be changed for one submission: the template's setting always applies. Change it in the template","exclusiveMinimum":"can't be changed for one submission: the template's setting always applies. Change it in the template","exclusive_maximum":"can't be changed for one submission: the template's setting always applies. Change it in the template","exclusiveMaximum":"can't be changed for one submission: the template's setting always applies. Change it in the template","currency":"can't be changed for one submission: the template's setting always applies. Change it in the template","min_length":"can't be changed for one submission: the template's setting always applies. Change it in the template","minLength":"can't be changed for one submission: the template's setting always applies. Change it in the template","auto_calculate_max_length":"can't be changed for one submission: the template's setting always applies. Change it in the template","autoCalculateMaxLength":"can't be changed for one submission: the template's setting always applies. Change it in the template","color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","colorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","colorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template","background_color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","backgroundColorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","background_color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","backgroundColorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template","check_color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","checkColorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","check_color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","checkColorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template","qrcode_color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","qrcodeColorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","qrcode_color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","qrcodeColorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template","shape_border_color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","shapeBorderColorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","shape_border_color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","shapeBorderColorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template","shape_fill_color_field_name":"can't be changed for one submission: the template's setting always applies. Change it in the template","shapeFillColorFieldName":"can't be changed for one submission: the template's setting always applies. Change it in the template","shape_fill_color_field_required":"can't be changed for one submission: the template's setting always applies. Change it in the template","shapeFillColorFieldRequired":"can't be changed for one submission: the template's setting always applies. Change it in the template"},"additionalProperties":false},"TemplateSummary":{"title":"TemplateSummary","type":"object","description":"A template in a list. Get a template by its ID for its HTML, defaults, field dependency rules and published versions.","required":["id","name","description","template_type","ready","document","parent_folder_id","path","version","latest_version","version_published_at","locked","add_signature_request_submission_id_footers","ai_field_naming_language","allow_additional_properties","allow_skipping_optional_fields","default_form_mode","editable_submissions","embed_domains","embed_edit_allow_settings","embed_edit_allow_versioning","embed_edit_allow_document_replacement","encrypt_pdfs","has_encrypt_pdfs_password","expire_submissions","expire_after","expiration_interval","merge_audit_trail_pdf","parse_dates_using_template_date_format","public_submissions","public_web_form","redirect_url","has_slack_webhook_url","last_changed_at","last_changed_by","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The template's ID."},"name":{"type":["string","null"],"maxLength":255,"description":"The template's name."},"description":{"type":["string","null"],"description":"Shown under the template's name at the top of its hosted forms, and used as their meta description. Not shown on embedded forms or signature requests."},"template_type":{"title":"TemplateType","type":"string","x-extensible-enum":["pdf","html"],"description":"`pdf`: fields placed on an uploaded PDF. `html`: a PDF rendered from HTML and SCSS. It can't be changed after the template is created.","x-type-description":"The kind of template: `pdf` (fields placed on an uploaded PDF) or `html` (a PDF rendered from HTML)."},"ready":{"type":"boolean","description":"Whether the template can generate PDFs. HTML templates are always ready. A PDF template is ready once its document has been processed (`document.state` is `processed`)."},"document":{"title":"TemplateDocument","type":["object","null"],"description":"The PDF of a PDF template. Null for HTML templates, and for a PDF template that has no PDF yet.","required":["filename","md5","state","error_message","field_reimport_state","page_count","page_dimensions","has_fillable_fields","page_processing_statuses","field_logic_status","download_url","permanent_url"],"properties":{"filename":{"type":["string","null"],"description":"The PDF's file name."},"md5":{"type":["string","null"],"description":"The MD5 hash of the PDF."},"state":{"type":"string","title":"TemplateDocumentState","x-type-description":"Where a template's PDF is in its processing.","x-extensible-enum":["pending","processed","password_required","malformed_pdf","unknown_error"],"description":"`pending` while DocSpring processes the PDF, then `processed`. `password_required`, `malformed_pdf` and `unknown_error` mean the PDF couldn't be processed, and `error_message` says why: upload it again or upload another one."},"error_message":{"type":["string","null"],"description":"Why the PDF couldn't be processed, and how to fix it. Null unless `state` is an error."},"field_reimport_state":{"type":"string","title":"FieldReimportState","x-type-description":"Whether a template's fields are being re-imported from its PDF.","x-extensible-enum":["none","requested","imported","no_fields"],"description":"Whether the fields are being re-imported from this PDF (`reimport_fields` when the PDF was replaced): `requested` while DocSpring processes the PDF, then `imported`, or `no_fields` when the PDF had no fillable fields and the template kept its fields. `none` when no re-import was asked for, or when it couldn't run (the PDF couldn't be processed, or the template was locked or published while it was)."},"page_count":{"type":"integer","description":"0 until the PDF has been processed."},"page_dimensions":{"type":["array","null"],"description":"Each page's width and height in PDF points. Null until the PDF has been processed.","items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"}}},"has_fillable_fields":{"type":["boolean","null"],"description":"Whether the PDF has fillable form fields. Null until DocSpring has read the PDF."},"page_processing_statuses":{"type":"array","description":"How processing is going on each page, in page order: its image, and its fields when DocSpring sets them up (`detect_fields` when the template was created). `state` becomes `processed` once every page is done. Empty until DocSpring has read the PDF, and for PDFs uploaded before DocSpring recorded page statuses.","items":{"title":"TemplatePageProcessingStatus","type":"object","x-type-description":"How processing is going on one page of a PDF template's PDF.","required":["image","fields","ai_naming","ai_error","detected_boxes"],"properties":{"image":{"title":"TemplatePageImageStatus","type":"string","x-extensible-enum":["pending","processed"],"description":"The page's image, which the template editor shows. `pending` until it's rendered.","x-type-description":"Whether a page's image has been rendered."},"fields":{"title":"TemplatePageFieldsStatus","type":"string","x-extensible-enum":["pending","naming","processed","failed","disabled"],"description":"Setting up the page's fields: `pending` while they're imported or detected, `naming` while AI names them, then `processed` or `failed`. `disabled` when DocSpring doesn't set up the page's fields.","x-type-description":"How setting up a page's fields is going."},"ai_naming":{"title":"TemplatePageAiNamingStatus","type":["string","null"],"x-extensible-enum":["failed","skipped"],"description":"`failed` or `skipped` when AI didn't name the page's fields as asked (`ai_error` says why), and the fields kept plain names. Null otherwise.","x-type-description":"Why AI didn't name a page's fields."},"ai_error":{"title":"TemplatePageAiError","type":["string","null"],"x-extensible-enum":["unavailable","error","credits","skipped"],"description":"Why AI naming failed or was skipped: `unavailable` (the AI service was unavailable: set up the fields again later), `error`, `credits` (the account had no free AI pages or credits left) or `skipped` (someone skipped AI setup in the template editor). Null when `ai_naming` is.","x-type-description":"Why AI naming failed or was skipped on a page."},"detected_boxes":{"type":["array","null"],"description":"While AI names the page's fields, the boxes field detection found: `[x, y, width, height]` in PDF points from the page's top-left corner. Null otherwise.","items":{"type":"array","minItems":4,"maxItems":4,"items":{"type":"number"}}}},"additionalProperties":false}},"field_logic_status":{"title":"TemplateFieldLogicStatus","type":["string","null"],"x-extensible-enum":["pending","processing","processed","failed","skipped"],"description":"AI field setup's last step, which reads the whole form once every page is done and can still rename fields and add conditional logic and required fields: `pending` or `processing` until it finishes, then `processed`, `failed` or `skipped`. Null until every page is done, and when there's no logic step to run (`field_logic` is `none`, or the PDF has no fields).","x-type-description":"How AI field setup's logic step is going."},"download_url":{"type":["string","null"],"description":"A temporary link to download the PDF."},"permanent_url":{"type":["string","null"],"description":"A link to download the PDF that doesn't expire. Null until the PDF has been processed."}},"x-type-description":"A PDF template's PDF.","additionalProperties":false},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder the template is in. Null for a template at the root. Setting it moves the template and all of its published versions."},"path":{"type":"string","description":"The path of the folder the template is in, such as `/Contracts`. `/` for a template at the root."},"version":{"type":["string","null"],"description":"The published version this is, such as `1.2.0`. Null for the draft."},"latest_version":{"type":["string","null"],"description":"The template's latest published version. Null if no version has been published."},"version_published_at":{"type":["string","null"],"format":"date-time","description":"When this version was published. Null for the draft."},"locked":{"type":"boolean","description":"A locked template can't be changed or deleted until it's unlocked (`locked` can always be changed)."},"add_signature_request_submission_id_footers":{"type":"boolean","description":"Print the submission ID in the footer of each page of PDFs signed through signature requests."},"ai_field_naming_language":{"title":"AiFieldNamingLanguage","type":["string","null"],"x-extensible-enum":["auto","english","form_language"],"description":"The language AI field setup names fields in: `auto` uses the form's language when it's written in the Latin alphabet without accents, and English otherwise; `english` always uses English; `form_language` uses the form's language and script. New templates take it from your account's template settings. Null for HTML templates.","x-type-description":"The language AI field setup names a PDF template's fields in."},"allow_additional_properties":{"type":"boolean","description":"Accept submission data with properties that aren't fields of the template."},"allow_skipping_optional_fields":{"type":"boolean","description":"Visual forms and signature request forms show the Continue button as soon as the required fields are filled in, without visiting each optional field. The `allowSkippingOptionalFields` embed option overrides it."},"default_form_mode":{"title":"TemplateFormMode","type":"string","x-extensible-enum":["web","visual","dual"],"description":"The hosted form that /templates/{template_id}/form shows when its URL has no `mode` parameter: `web` (the web form), `visual` (the visual form, where fields are filled in on the PDF) or `dual` (both, in tabs). HTML templates have no visual form, so `web` is the only value they accept.","x-type-description":"Which hosted form a template's form link opens."},"editable_submissions":{"type":"boolean","description":"Generate PDFs whose text and check fields stay fillable (\"Generate Editable PDFs\"). A submission's `editable` overrides it."},"embed_domains":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":255},"description":"The sites where the template's signature requests, forms and embedded template editor can be loaded: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). When it's empty, live signature requests don't load on any site, and the embedded template editor loads on every site."},"embed_edit_allow_settings":{"type":"boolean","description":"Allow the embedded template editor to change sensitive template settings (webhooks, redirect URL, encryption, public access, expiration and so on)."},"embed_edit_allow_versioning":{"type":"boolean","description":"Allow the embedded template editor to publish, restore, compare and delete published versions."},"embed_edit_allow_document_replacement":{"type":"boolean","description":"Allow the embedded template editor to replace the template's PDF."},"encrypt_pdfs":{"type":"boolean","description":"Encrypt generated PDFs with `encrypt_pdfs_password`."},"has_encrypt_pdfs_password":{"type":"boolean","description":"Whether `encrypt_pdfs_password` is set."},"expire_submissions":{"type":"boolean","description":"Delete each submission's data and PDF after `expire_after` `expiration_interval`."},"expire_after":{"type":"integer","minimum":1,"maximum":5256000,"description":"How many `expiration_interval`s a submission's data and PDF are kept for, when `expire_submissions` is on. At most 5256000 (10 years in minutes)."},"expiration_interval":{"title":"ExpirationInterval","type":"string","x-extensible-enum":["minutes","hours","days"],"description":"The unit of `expire_after`.","x-type-description":"A unit of time."},"merge_audit_trail_pdf":{"type":"boolean","description":"Add the audit trail to the end of PDFs signed through signature requests."},"parse_dates_using_template_date_format":{"type":"boolean","description":"Date fields also accept NN/NN/YYYY dates (with slashes, dashes or dots), read in the order of the template's default date format: month first for %m/%d/%Y, day first for %d/%m/%Y. When false, date fields only accept YYYY-MM-DD. Applies to PDF templates: an HTML template's date fields only accept YYYY-MM-DD. Date fields that include a time take RFC 3339 date-times either way."},"public_submissions":{"type":"boolean","description":"Allow anyone with a submission's ID to download its PDF."},"public_web_form":{"type":"boolean","description":"Allow anyone to fill in the template's web form."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where the web form sends people after they submit it."},"has_slack_webhook_url":{"type":"boolean","description":"Whether `slack_webhook_url` is set."},"last_changed_at":{"type":["string","null"],"format":"date-time","description":"When the draft was last changed."},"last_changed_by":{"title":"TemplateActor","type":["object","null"],"description":"Who last changed the draft: a user in your account, an API token, or someone using the embedded template editor. Null if no change has been recorded.","required":["type","user_id","external_id","name","email"],"properties":{"type":{"type":"string","title":"TemplateActorType","x-type-description":"Who changed a template (a user in your account, an API token, or someone using the embedded template editor).","x-extensible-enum":["user","api","external_user"],"description":"`user`: a user in your account. `api`: an API token. `external_user`: someone using the embedded template editor, as identified by your app."},"user_id":{"type":["string","null"],"description":"The user's ID, for `user`."},"external_id":{"type":["string","null"],"description":"The ID your app gave the embedded editor's user, for `external_user`."},"name":{"type":["string","null"],"description":"The user's name, or the name your app gave the embedded editor's user."},"email":{"type":["string","null"],"description":"The email address your app gave the embedded editor's user, for `external_user`."}},"x-type-description":"A user in your account, an API token, or someone using the embedded template editor.","additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"When the template was created."},"updated_at":{"type":"string","format":"date-time","description":"When the template was last updated."}},"additionalProperties":true},"Template":{"title":"Template","type":"object","description":"A template that generates PDFs from submission data.","required":["id","name","description","template_type","ready","document","parent_folder_id","path","version","latest_version","version_published_at","locked","add_signature_request_submission_id_footers","ai_field_naming_language","allow_additional_properties","allow_skipping_optional_fields","default_form_mode","editable_submissions","embed_domains","embed_edit_allow_settings","embed_edit_allow_versioning","embed_edit_allow_document_replacement","encrypt_pdfs","has_encrypt_pdfs_password","expire_submissions","expire_after","expiration_interval","merge_audit_trail_pdf","parse_dates_using_template_date_format","public_submissions","public_web_form","redirect_url","has_slack_webhook_url","last_changed_at","last_changed_by","created_at","updated_at","defaults","field_dependencies","html","scss","header_html","footer_html","html_engine_options","embed_edit_token","versions"],"properties":{"id":{"type":"string","description":"The template's ID."},"name":{"type":["string","null"],"maxLength":255,"description":"The template's name."},"description":{"type":["string","null"],"description":"Shown under the template's name at the top of its hosted forms, and used as their meta description. Not shown on embedded forms or signature requests."},"template_type":{"title":"TemplateType","type":"string","x-extensible-enum":["pdf","html"],"description":"`pdf`: fields placed on an uploaded PDF. `html`: a PDF rendered from HTML and SCSS. It can't be changed after the template is created.","x-type-description":"The kind of template: `pdf` (fields placed on an uploaded PDF) or `html` (a PDF rendered from HTML)."},"ready":{"type":"boolean","description":"Whether the template can generate PDFs. HTML templates are always ready. A PDF template is ready once its document has been processed (`document.state` is `processed`)."},"document":{"title":"TemplateDocument","type":["object","null"],"description":"The PDF of a PDF template. Null for HTML templates, and for a PDF template that has no PDF yet.","required":["filename","md5","state","error_message","field_reimport_state","page_count","page_dimensions","has_fillable_fields","page_processing_statuses","field_logic_status","download_url","permanent_url"],"properties":{"filename":{"type":["string","null"],"description":"The PDF's file name."},"md5":{"type":["string","null"],"description":"The MD5 hash of the PDF."},"state":{"type":"string","title":"TemplateDocumentState","x-type-description":"Where a template's PDF is in its processing.","x-extensible-enum":["pending","processed","password_required","malformed_pdf","unknown_error"],"description":"`pending` while DocSpring processes the PDF, then `processed`. `password_required`, `malformed_pdf` and `unknown_error` mean the PDF couldn't be processed, and `error_message` says why: upload it again or upload another one."},"error_message":{"type":["string","null"],"description":"Why the PDF couldn't be processed, and how to fix it. Null unless `state` is an error."},"field_reimport_state":{"type":"string","title":"FieldReimportState","x-type-description":"Whether a template's fields are being re-imported from its PDF.","x-extensible-enum":["none","requested","imported","no_fields"],"description":"Whether the fields are being re-imported from this PDF (`reimport_fields` when the PDF was replaced): `requested` while DocSpring processes the PDF, then `imported`, or `no_fields` when the PDF had no fillable fields and the template kept its fields. `none` when no re-import was asked for, or when it couldn't run (the PDF couldn't be processed, or the template was locked or published while it was)."},"page_count":{"type":"integer","description":"0 until the PDF has been processed."},"page_dimensions":{"type":["array","null"],"description":"Each page's width and height in PDF points. Null until the PDF has been processed.","items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"}}},"has_fillable_fields":{"type":["boolean","null"],"description":"Whether the PDF has fillable form fields. Null until DocSpring has read the PDF."},"page_processing_statuses":{"type":"array","description":"How processing is going on each page, in page order: its image, and its fields when DocSpring sets them up (`detect_fields` when the template was created). `state` becomes `processed` once every page is done. Empty until DocSpring has read the PDF, and for PDFs uploaded before DocSpring recorded page statuses.","items":{"title":"TemplatePageProcessingStatus","type":"object","x-type-description":"How processing is going on one page of a PDF template's PDF.","required":["image","fields","ai_naming","ai_error","detected_boxes"],"properties":{"image":{"title":"TemplatePageImageStatus","type":"string","x-extensible-enum":["pending","processed"],"description":"The page's image, which the template editor shows. `pending` until it's rendered.","x-type-description":"Whether a page's image has been rendered."},"fields":{"title":"TemplatePageFieldsStatus","type":"string","x-extensible-enum":["pending","naming","processed","failed","disabled"],"description":"Setting up the page's fields: `pending` while they're imported or detected, `naming` while AI names them, then `processed` or `failed`. `disabled` when DocSpring doesn't set up the page's fields.","x-type-description":"How setting up a page's fields is going."},"ai_naming":{"title":"TemplatePageAiNamingStatus","type":["string","null"],"x-extensible-enum":["failed","skipped"],"description":"`failed` or `skipped` when AI didn't name the page's fields as asked (`ai_error` says why), and the fields kept plain names. Null otherwise.","x-type-description":"Why AI didn't name a page's fields."},"ai_error":{"title":"TemplatePageAiError","type":["string","null"],"x-extensible-enum":["unavailable","error","credits","skipped"],"description":"Why AI naming failed or was skipped: `unavailable` (the AI service was unavailable: set up the fields again later), `error`, `credits` (the account had no free AI pages or credits left) or `skipped` (someone skipped AI setup in the template editor). Null when `ai_naming` is.","x-type-description":"Why AI naming failed or was skipped on a page."},"detected_boxes":{"type":["array","null"],"description":"While AI names the page's fields, the boxes field detection found: `[x, y, width, height]` in PDF points from the page's top-left corner. Null otherwise.","items":{"type":"array","minItems":4,"maxItems":4,"items":{"type":"number"}}}},"additionalProperties":false}},"field_logic_status":{"title":"TemplateFieldLogicStatus","type":["string","null"],"x-extensible-enum":["pending","processing","processed","failed","skipped"],"description":"AI field setup's last step, which reads the whole form once every page is done and can still rename fields and add conditional logic and required fields: `pending` or `processing` until it finishes, then `processed`, `failed` or `skipped`. Null until every page is done, and when there's no logic step to run (`field_logic` is `none`, or the PDF has no fields).","x-type-description":"How AI field setup's logic step is going."},"download_url":{"type":["string","null"],"description":"A temporary link to download the PDF."},"permanent_url":{"type":["string","null"],"description":"A link to download the PDF that doesn't expire. Null until the PDF has been processed."}},"x-type-description":"A PDF template's PDF.","additionalProperties":false},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder the template is in. Null for a template at the root. Setting it moves the template and all of its published versions."},"path":{"type":"string","description":"The path of the folder the template is in, such as `/Contracts`. `/` for a template at the root."},"version":{"type":["string","null"],"description":"The published version this is, such as `1.2.0`. Null for the draft."},"latest_version":{"type":["string","null"],"description":"The template's latest published version. Null if no version has been published."},"version_published_at":{"type":["string","null"],"format":"date-time","description":"When this version was published. Null for the draft."},"locked":{"type":"boolean","description":"A locked template can't be changed or deleted until it's unlocked (`locked` can always be changed)."},"add_signature_request_submission_id_footers":{"type":"boolean","description":"Print the submission ID in the footer of each page of PDFs signed through signature requests."},"ai_field_naming_language":{"title":"AiFieldNamingLanguage","type":["string","null"],"x-extensible-enum":["auto","english","form_language"],"description":"The language AI field setup names fields in: `auto` uses the form's language when it's written in the Latin alphabet without accents, and English otherwise; `english` always uses English; `form_language` uses the form's language and script. New templates take it from your account's template settings. Null for HTML templates.","x-type-description":"The language AI field setup names a PDF template's fields in."},"allow_additional_properties":{"type":"boolean","description":"Accept submission data with properties that aren't fields of the template."},"allow_skipping_optional_fields":{"type":"boolean","description":"Visual forms and signature request forms show the Continue button as soon as the required fields are filled in, without visiting each optional field. The `allowSkippingOptionalFields` embed option overrides it."},"default_form_mode":{"title":"TemplateFormMode","type":"string","x-extensible-enum":["web","visual","dual"],"description":"The hosted form that /templates/{template_id}/form shows when its URL has no `mode` parameter: `web` (the web form), `visual` (the visual form, where fields are filled in on the PDF) or `dual` (both, in tabs). HTML templates have no visual form, so `web` is the only value they accept.","x-type-description":"Which hosted form a template's form link opens."},"editable_submissions":{"type":"boolean","description":"Generate PDFs whose text and check fields stay fillable (\"Generate Editable PDFs\"). A submission's `editable` overrides it."},"embed_domains":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":255},"description":"The sites where the template's signature requests, forms and embedded template editor can be loaded: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). When it's empty, live signature requests don't load on any site, and the embedded template editor loads on every site."},"embed_edit_allow_settings":{"type":"boolean","description":"Allow the embedded template editor to change sensitive template settings (webhooks, redirect URL, encryption, public access, expiration and so on)."},"embed_edit_allow_versioning":{"type":"boolean","description":"Allow the embedded template editor to publish, restore, compare and delete published versions."},"embed_edit_allow_document_replacement":{"type":"boolean","description":"Allow the embedded template editor to replace the template's PDF."},"encrypt_pdfs":{"type":"boolean","description":"Encrypt generated PDFs with `encrypt_pdfs_password`."},"has_encrypt_pdfs_password":{"type":"boolean","description":"Whether `encrypt_pdfs_password` is set."},"expire_submissions":{"type":"boolean","description":"Delete each submission's data and PDF after `expire_after` `expiration_interval`."},"expire_after":{"type":"integer","minimum":1,"maximum":5256000,"description":"How many `expiration_interval`s a submission's data and PDF are kept for, when `expire_submissions` is on. At most 5256000 (10 years in minutes)."},"expiration_interval":{"title":"ExpirationInterval","type":"string","x-extensible-enum":["minutes","hours","days"],"description":"The unit of `expire_after`.","x-type-description":"A unit of time."},"merge_audit_trail_pdf":{"type":"boolean","description":"Add the audit trail to the end of PDFs signed through signature requests."},"parse_dates_using_template_date_format":{"type":"boolean","description":"Date fields also accept NN/NN/YYYY dates (with slashes, dashes or dots), read in the order of the template's default date format: month first for %m/%d/%Y, day first for %d/%m/%Y. When false, date fields only accept YYYY-MM-DD. Applies to PDF templates: an HTML template's date fields only accept YYYY-MM-DD. Date fields that include a time take RFC 3339 date-times either way."},"public_submissions":{"type":"boolean","description":"Allow anyone with a submission's ID to download its PDF."},"public_web_form":{"type":"boolean","description":"Allow anyone to fill in the template's web form."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where the web form sends people after they submit it."},"has_slack_webhook_url":{"type":"boolean","description":"Whether `slack_webhook_url` is set."},"last_changed_at":{"type":["string","null"],"format":"date-time","description":"When the draft was last changed."},"last_changed_by":{"title":"TemplateActor","type":["object","null"],"description":"Who last changed the draft: a user in your account, an API token, or someone using the embedded template editor. Null if no change has been recorded.","required":["type","user_id","external_id","name","email"],"properties":{"type":{"type":"string","title":"TemplateActorType","x-type-description":"Who changed a template (a user in your account, an API token, or someone using the embedded template editor).","x-extensible-enum":["user","api","external_user"],"description":"`user`: a user in your account. `api`: an API token. `external_user`: someone using the embedded template editor, as identified by your app."},"user_id":{"type":["string","null"],"description":"The user's ID, for `user`."},"external_id":{"type":["string","null"],"description":"The ID your app gave the embedded editor's user, for `external_user`."},"name":{"type":["string","null"],"description":"The user's name, or the name your app gave the embedded editor's user."},"email":{"type":["string","null"],"description":"The email address your app gave the embedded editor's user, for `external_user`."}},"x-type-description":"A user in your account, an API token, or someone using the embedded template editor.","additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"When the template was created."},"updated_at":{"type":"string","format":"date-time","description":"When the template was last updated."},"defaults":{"$ref":"#/components/schemas/TemplateDefaults"},"field_dependencies":{"type":"array","description":"Conditional logic: each rule shows or hides its target fields, or makes them required, depending on the values of other fields.","items":{"$ref":"#/components/schemas/TemplateFieldDependency"}},"html":{"type":["string","null"],"description":"The HTML of an HTML template, as a Liquid template. Null for PDF templates."},"scss":{"type":["string","null"],"description":"The SCSS of an HTML template."},"header_html":{"type":["string","null"],"description":"The HTML printed at the top of each page of an HTML template."},"footer_html":{"type":["string","null"],"description":"The HTML printed at the bottom of each page of an HTML template."},"html_engine_options":{"title":"HtmlEngineOptions","type":["object","null"],"description":"How an HTML template's PDFs are printed. Null for PDF templates. Setting it replaces the whole object: options left out use their defaults.","x-type-description":"How an HTML template's PDFs are printed.","required":["format","scale","landscape","print_background","margin_top","margin_bottom","margin_left","margin_right"],"properties":{"format":{"title":"PageFormat","type":"string","x-extensible-enum":["Letter","Legal","Tabloid","Ledger","CR80","A0","A1","A2","A3","A4","A5","A6","Custom"],"description":"The paper size. `Custom` uses `width` and `height`.","x-type-description":"A paper size, or `Custom`."},"width":{"type":"string","description":"The page width for the `Custom` format, with a unit (`8.5in`, `210mm`)."},"height":{"type":"string","description":"The page height for the `Custom` format, with a unit."},"scale":{"type":"number","exclusiveMinimum":0,"description":"How much to scale the page, such as `0.8`. `1` prints it at its normal size."},"landscape":{"type":"boolean","description":"Print pages in landscape orientation."},"print_background":{"type":"boolean","description":"Print background colors and images."},"margin_top":{"type":"string","description":"The top margin, with a unit, such as `1in` or `20mm`."},"margin_bottom":{"type":"string","description":"The bottom margin, with a unit."},"margin_left":{"type":"string","description":"The left margin, with a unit."},"margin_right":{"type":"string","description":"The right margin, with a unit."}},"additionalProperties":false},"embed_edit_token":{"type":["string","null"],"description":"The token that opens the template in the embedded template editor."},"versions":{"type":"array","description":"The template's published versions, newest first (up to 100).","items":{"$ref":"#/components/schemas/TemplateVersion"}}},"additionalProperties":true},"TemplateSummaryList":{"title":"TemplateSummaryList","type":"object","description":"A page of templates (drafts), newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/TemplateSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"TemplateVersion":{"title":"TemplateVersion","type":"object","description":"A published version of a template.","required":["version","description","published_at","published_by"],"properties":{"version":{"type":"string","description":"The version number, such as `1.2.0`."},"description":{"type":["string","null"],"description":"What changed in the version, as written when it was published."},"published_at":{"type":"string","format":"date-time","description":"When the version was published."},"published_by":{"title":"TemplateActor","type":["object","null"],"description":"Who published the version. Null when that wasn't recorded.","required":["type","user_id","external_id","name","email"],"properties":{"type":{"type":"string","title":"TemplateActorType","x-type-description":"Who changed a template (a user in your account, an API token, or someone using the embedded template editor).","x-extensible-enum":["user","api","external_user"],"description":"`user`: a user in your account. `api`: an API token. `external_user`: someone using the embedded template editor, as identified by your app."},"user_id":{"type":["string","null"],"description":"The user's ID, for `user`."},"external_id":{"type":["string","null"],"description":"The ID your app gave the embedded editor's user, for `external_user`."},"name":{"type":["string","null"],"description":"The user's name, or the name your app gave the embedded editor's user."},"email":{"type":["string","null"],"description":"The email address your app gave the embedded editor's user, for `external_user`."}},"x-type-description":"A user in your account, an API token, or someone using the embedded template editor.","additionalProperties":false}},"additionalProperties":true},"TemplateDefaults":{"title":"TemplateDefaults","type":"object","description":"The default style of the template's fields. Each field can override it.","properties":{"typeface":{"title":"Typeface","type":["string","null"],"x-extensible-enum":["Inconsolata","Roboto Mono","Ubuntu Mono","Menlo","Courier","Helvetica","Arial","Calibri","Open Sans","Roboto","Lato","Poppins","Public Sans","Questrial","Times New Roman","Dancing Script","Lovtony Script"],"description":"The font of text fields.","x-type-description":"One of the template editor's typefaces."},"font_size":{"type":["number","null"],"description":"The font size in points, a whole number."},"character_spacing":{"type":["number","null"],"description":"Extra space between characters, in points (0 to 50)."},"color":{"type":["string","null"],"description":"The text color, as 6 hex digits without `#`, such as `444444`."},"background_color":{"type":["string","null"],"description":"The field's background color, as 6 hex digits."},"bold":{"type":"boolean","description":"Print text in bold."},"uppercase":{"type":"boolean","description":"Print text in capital letters."},"alignment":{"title":"TextAlignment","type":"string","x-extensible-enum":["left","center","right","justify"],"description":"How text is aligned in its field. `justify` lines up both edges of every line of multiline text except the last of each paragraph.","x-type-description":"A horizontal text alignment."},"opacity":{"type":"number","minimum":0,"maximum":1,"description":"The opacity of the field's content, from 0 (invisible) to 1."},"date_format":{"type":["string","null"],"description":"How date fields are printed, as a strftime format such as `%m/%d/%Y`."},"date_time_format":{"type":["string","null"],"description":"How date-time fields are printed, as a strftime format such as `%m/%d/%Y %H:%M:%S`."},"check_color":{"type":["string","null"],"description":"The color of check marks, as 6 hex digits."},"check_character":{"title":"CheckCharacter","type":["string","null"],"x-extensible-enum":["&#10003;","&#10004;","&#10006;","&#10007;","&#10008;"],"x-enum-varnames":["CHECK","HEAVY_CHECK","MULTIPLICATION_X","BALLOT_X","HEAVY_BALLOT_X"],"description":"The character that a ticked check box prints.","x-type-description":"A check mark or cross, as the HTML entity of its character: ✓ (`&#10003;`), ✔ (`&#10004;`), ✖ (`&#10006;`), ✗ (`&#10007;`) or ✘ (`&#10008;`)."},"check_background_color":{"type":["string","null"],"description":"The check box's background color, as 6 hex digits."},"required_field_background_color":{"type":["string","null"],"description":"The background color that highlights required fields on visual forms and signature request forms, as 6 hex digits. PDFs don't print it."},"true_text":{"type":["string","null"],"description":"The text a boolean field prints for `true`."},"false_text":{"type":["string","null"],"description":"The text a boolean field prints for `false`."},"shape_fill_color":{"type":["string","null"],"description":"The fill color of shapes, as 6 hex digits."},"shape_border_color":{"type":["string","null"],"description":"The border color of shapes, as 6 hex digits."},"shape_border_width":{"type":"number","minimum":0,"description":"The border width of shapes, in whole points (at least 1)."}},"additionalProperties":true},"TemplateFieldDependency":{"title":"TemplateFieldDependency","type":"object","description":"A conditional logic rule: when other fields' values meet its conditions, it shows its target fields, makes them required, or both.","required":["action","conditions","targets"],"properties":{"action":{"title":"TemplateFieldDependencyAction","type":"string","x-extensible-enum":["require_and_show","show","require"],"description":"What the rule does to its targets when its conditions are met.","x-type-description":"What a conditional logic rule does to its target fields."},"match":{"title":"TemplateFieldDependencyMatch","type":"string","x-extensible-enum":["all","any"],"description":"Whether all of the conditions (the default) or any of them must be met.","x-type-description":"Whether all of a rule's conditions or any of them must be met."},"conditions":{"type":"array","items":{"title":"TemplateFieldDependencyCondition","type":"object","required":["field","operator"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"title":"TemplateFieldDependencyOperator","type":"string","x-extensible-enum":["present","blank","equals","not_equals","in","gt","gte","lt","lte","range"],"description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","x-type-description":"How a condition compares a field's value."},"value":{"description":"The value to compare the field's value with."},"range_max":{"type":["number","string","null"],"description":"The upper end of a `range`, a number (or a number as a string, as the template editor saves it)."}},"x-type-description":"A condition on a field's value.","additionalProperties":false},"description":"The conditions on other fields' values."},"targets":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"The names of the fields the rule shows or makes required."},"group":{"type":"string","description":"Marks a rule made for a field group in the template editor. Its targets outside the group are removed when the template is saved, and the rule is removed once the group has no fields."}},"additionalProperties":true},"TemplateDataSchema":{"title":"TemplateDataSchema","type":"object","additionalProperties":true,"description":"The JSON Schema of the template's submission data: one property for each field, with its type, format and whether it's required. Its `$schema` says which draft it uses (draft-07 for newer accounts, draft-04 before)."},"TemplateModelCode":{"title":"TemplateModelCode","type":"object","description":"Typed code for the template's submission data, for an app that creates submissions.","required":["lang","root_type_name","code"],"properties":{"lang":{"title":"ModelCodeLanguage","type":"string","x-extensible-enum":["typescript","javascript","ruby","python","php","java","csharp","elixir","go"],"description":"The language of `code`.","x-type-description":"A language that DocSpring generates typed code in."},"root_type_name":{"type":"string","description":"The name of the type for the whole submission data object."},"code":{"type":"string","description":"The source code of the types, starting with `root_type_name`."}},"additionalProperties":true},"UploadPresign":{"title":"UploadPresign","type":"object","description":"A presigned S3 form for uploading a file. POST `fields` and the file (as `file`, last) to `url` as multipart/form-data. Then use `fields.key` as the `cache_id` when you create a custom file.","required":["url","method","fields","headers"],"properties":{"url":{"type":"string","format":"uri","description":"The S3 URL to upload the file to."},"method":{"type":"string","title":"UploadMethod","x-type-description":"The HTTP method to upload a file with.","x-extensible-enum":["post"],"description":"The HTTP method for the upload."},"fields":{"type":"object","description":"Form fields to send with the file. Send them all, as they are. `key` is the uploaded file's ID: pass it as `cache_id`.","required":["key"],"additionalProperties":{"type":"string"}},"headers":{"type":"object","description":"Headers to send with the upload.","additionalProperties":{"type":"string"}}},"additionalProperties":true},"Webhook":{"title":"Webhook","type":"object","description":"An endpoint that DocSpring sends a POST request to when a subscribed event happens.","required":["id","name","url","enabled","event_types","mode","version","api_token_ids","template_ids","folder_ids","include_submission_data","strip_fields","headers","consecutive_failures","last_failure_at","disabled_at","disabled_reason","secret","created_at","updated_at"],"properties":{"id":{"type":"string","description":"The webhook's ID."},"name":{"type":["string","null"],"maxLength":255,"description":"A name for the webhook, shown in the dashboard."},"url":{"type":"string","format":"uri","description":"The endpoint that receives webhook POST requests."},"enabled":{"type":"boolean","description":"Whether DocSpring sends events to the webhook. Webhooks are disabled after repeated failures."},"event_types":{"type":"array","minItems":1,"uniqueItems":true,"description":"The events the webhook subscribes to. A webhook made in the dashboard can also subscribe to API token, account integration and user events, which are listed with their own names.","items":{"title":"WebhookEventType","type":"string","x-extensible-enum":["submission.processed","submission.failed","submission.declined","signature_request.viewed","signature_request.completed","signature_request.declined","combined_pdf.processed","combined_pdf.failed","submission_batch.processed","submission_batch.failed","submission.created","submission.updated","submission.expired","signature_request.updated","combined_pdf.expired","template.created","template.updated","template.deleted","webhook.created","webhook.updated","webhook.deleted","custom_file.created","folder.created","folder.updated","folder.deleted"],"x-type-description":"An event that a webhook can subscribe to."}},"mode":{"title":"WebhookMode","type":["string","null"],"x-extensible-enum":["test","live"],"description":"Only send events for test or live submissions. Null sends both.","x-type-description":"Which submissions a webhook sends events for, test or live."},"version":{"type":"integer","x-extensible-enum":[1,2,3,4],"description":"The format of the requests DocSpring sends. Webhooks created with API v2 use 4: each event's `data` is the resource as API v2 returns it. Webhooks made in the dashboard or with API v1 use 3, which has API v1's resources and names (`combined_submission`, `submission_data_request`). Versions 1 and 2 are legacy formats for submission events."},"api_token_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events from these API tokens. Combined with the other scope lists using OR. Applies to submission, signature request, combined PDF, submission batch and custom file events."},"template_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for these templates. Combined with the other scope lists using OR. Applies to submission, signature request and template events."},"folder_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for templates in these folders, including their subfolders. Combined with the other scope lists using OR. Applies to submission, signature request, template and folder events."},"include_submission_data":{"type":"boolean","description":"Include the submission's field data in the payload. When false, the submission's data and truncated_text, and each signature request's data, ip_address and user_agent, are null."},"strip_fields":{"type":"array","items":{"type":"string"},"description":"Dot-separated paths to remove from the event's data object. Form fields live under `data` (`data.ssn` removes the ssn field). A bare name removes a top-level key (`metadata` removes the whole metadata object)."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers to send with each request."},"consecutive_failures":{"type":"integer","description":"How many deliveries in a row have failed."},"last_failure_at":{"type":["string","null"],"format":"date-time","description":"When a delivery last failed."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When the webhook was disabled. Null while it is enabled."},"disabled_reason":{"type":["string","null"],"description":"Why the webhook was disabled, such as after repeated failures."},"secret":{"type":["string","null"],"description":"The key that signs each request (the X-DocSpring-Signature header), so you can check that a request came from DocSpring. Null for some webhooks created before signing existed."},"created_at":{"type":"string","format":"date-time","description":"When the webhook was created."},"updated_at":{"type":"string","format":"date-time","description":"When the webhook was last updated."}},"additionalProperties":true},"WebhookList":{"title":"WebhookList","type":"object","description":"A page of webhooks, newest first.","required":["data","next_cursor"],"properties":{"data":{"type":"array","description":"The items on this page.","items":{"$ref":"#/components/schemas/Webhook"}},"next_cursor":{"type":["string","null"],"description":"Pass it as `cursor` to get the next page. Null on the last page."}},"additionalProperties":true},"SubmissionSourcePdf":{"title":"SubmissionSourcePdf","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","const":"submission"},"id":{"type":"string","minLength":1,"description":"The ID of the submission, combined PDF, template or custom file."}},"additionalProperties":false,"x-not-allowed-properties":{"url":"isn't used by 'submission' source PDFs. Remove it","template_version":"isn't used by 'submission' source PDFs. Remove it","processed":"isn't used by 'submission' source PDFs. Remove it"},"writeOnly":true,"description":"A submission's PDF to merge."},"CombinedPdfSourcePdf":{"title":"CombinedPdfSourcePdf","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","const":"combined_pdf"},"id":{"type":"string","minLength":1,"description":"The ID of the submission, combined PDF, template or custom file."}},"additionalProperties":false,"x-not-allowed-properties":{"url":"isn't used by 'combined_pdf' source PDFs. Remove it","template_version":"isn't used by 'combined_pdf' source PDFs. Remove it","processed":"isn't used by 'combined_pdf' source PDFs. Remove it"},"writeOnly":true,"description":"Another combined PDF to merge."},"TemplateSourcePdf":{"title":"TemplateSourcePdf","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","const":"template"},"id":{"type":"string","minLength":1,"description":"The ID of the submission, combined PDF, template or custom file."},"template_version":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","description":"For a `template` source, the version to use: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published).","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"processed":{"type":"boolean","description":"For a `template` source: true (the default) merges the template's processed PDF, which is the PDF submissions are filled in on (decrypted, with its form fields removed). false merges the PDF as it was uploaded."}},"additionalProperties":false,"x-not-allowed-properties":{"url":"isn't used by 'template' source PDFs. Remove it"},"writeOnly":true,"description":"A template's PDF to merge."},"CustomFileSourcePdf":{"title":"CustomFileSourcePdf","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","const":"custom_file"},"id":{"type":"string","minLength":1,"description":"The ID of the submission, combined PDF, template or custom file."}},"additionalProperties":false,"x-not-allowed-properties":{"url":"isn't used by 'custom_file' source PDFs. Remove it","template_version":"isn't used by 'custom_file' source PDFs. Remove it","processed":"isn't used by 'custom_file' source PDFs. Remove it"},"writeOnly":true,"description":"A custom file to merge (POST /custom_files)."},"UrlSourcePdf":{"title":"UrlSourcePdf","type":"object","required":["type","url"],"properties":{"type":{"type":"string","description":"What the PDF is: a submission's PDF, another combined PDF, a template's PDF, a custom file (POST /custom_files) or a PDF to download from a URL.","const":"url"},"url":{"type":"string","format":"uri","description":"For a `url` source, the URL to download the PDF from. Removed once the combined PDF has expired."}},"additionalProperties":false,"x-not-allowed-properties":{"id":"isn't used by 'url' source PDFs. Remove it","template_version":"isn't used by 'url' source PDFs. Remove it","processed":"isn't used by 'url' source PDFs. Remove it"},"writeOnly":true,"description":"A PDF to download from a URL and merge."},"FieldPresenceCondition":{"title":"FieldPresenceCondition","type":"object","required":["field","operator"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"type":"string","description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","title":"FieldPresenceOperator","enum":["present","blank"],"x-type-description":"The operators a FieldPresenceCondition takes."}},"additionalProperties":false,"x-not-allowed-properties":{"value":"isn't used by 'present' or 'blank' conditions. Remove it","range_max":"isn't used by 'present' or 'blank' conditions. Remove it"},"writeOnly":true,"description":"A condition on whether a field has a value."},"FieldEqualsCondition":{"title":"FieldEqualsCondition","type":"object","required":["field","operator","value"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"type":"string","description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","title":"FieldEqualsOperator","enum":["equals","not_equals"],"x-type-description":"The operators a FieldEqualsCondition takes."},"value":{"description":"The value the field's value is compared with.","type":["string","number","boolean"]}},"additionalProperties":false,"x-not-allowed-properties":{"range_max":"isn't used by 'equals' or 'not_equals' conditions. Remove it"},"writeOnly":true,"description":"A condition on whether a field's value is (or isn't) a value."},"FieldInCondition":{"title":"FieldInCondition","type":"object","required":["field","operator","value"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"type":"string","description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","const":"in"},"value":{"description":"The values the field's value must be one of.","type":"array","minItems":1,"items":{"type":["string","number","boolean"],"minLength":1}}},"additionalProperties":false,"x-not-allowed-properties":{"range_max":"isn't used by 'in' conditions. Remove it"},"writeOnly":true,"description":"A condition on whether a field's value is one of a list."},"FieldComparisonCondition":{"title":"FieldComparisonCondition","type":"object","required":["field","operator","value"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"type":"string","description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","title":"FieldComparisonOperator","enum":["gt","gte","lt","lte"],"x-type-description":"The operators a FieldComparisonCondition takes."},"value":{"description":"The number the field's value is compared with, or a number as a string (as the template editor saves it). The field must be a number field.","type":["number","string"],"pattern":"^-?\\d+(\\.\\d+)?([eE][-+]?\\d+)?$","x-pattern-message":"must be a number, like 10 or 2.5"}},"additionalProperties":false,"x-not-allowed-properties":{"range_max":"isn't used by 'gt', 'gte', 'lt' or 'lte' conditions. Remove it"},"writeOnly":true,"description":"A condition comparing a number field's value with a number."},"FieldRangeCondition":{"title":"FieldRangeCondition","type":"object","required":["field","operator"],"properties":{"field":{"type":"string","description":"The name of the field whose value is compared."},"operator":{"type":"string","description":"How the field's value is compared with `value`. `in`: one of a list. `range`: from `value` to `range_max`.","const":"range"},"value":{"description":"The lower end of the range, a number (or a number as a string, as the template editor saves it). Null or left out for no lower end. A range needs `value`, `range_max` or both.","type":["number","string","null"],"pattern":"^-?\\d+(\\.\\d+)?([eE][-+]?\\d+)?$","x-pattern-message":"must be a number, like 10 or 2.5"},"range_max":{"type":["number","string","null"],"description":"The upper end of the range, a number (or a number as a string, as the template editor saves it). Null or left out for no upper end.","pattern":"^-?\\d+(\\.\\d+)?([eE][-+]?\\d+)?$","x-pattern-message":"must be a number, like 10 or 2.5"}},"additionalProperties":false,"writeOnly":true,"description":"A condition on whether a number field's value is in a range."}}},"paths":{"/authentication":{"get":{"summary":"Test authentication","tags":["Authentication"],"operationId":"testAuthentication","description":"Checks whether your API token is valid by making an authenticated request. This endpoint is useful for\nverifying credentials during setup or troubleshooting issues.\n","externalDocs":{"url":"https://docspring.com/docs/api-guide/authentication/","description":"Learn how to authenticate with the DocSpring API"},"responses":{"200":{"description":"authentication succeeded","content":{"application/json":{"examples":{"authentication succeeded":{"summary":"authentication succeeded","value":{"authenticated":true}}},"schema":{"$ref":"#/components/schemas/AuthenticationCheck"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/combined_pdfs":{"get":{"summary":"List combined PDFs","tags":["Combined PDFs"],"operationId":"listCombinedPdfs","description":"Returns the combined PDFs in your account, newest first, one page at a time.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"combined PDFs","content":{"application/json":{"examples":{"combined PDFs":{"summary":"combined PDFs","value":{"data":[{"id":"com_1234567890abcdef06","state":"pending","source_pdfs":[{"type":"url","url":"https://example.com/terms.pdf"}],"metadata":{},"has_password":false,"delete_custom_files":false,"error_message":null,"files":{},"actions":[],"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T08:50:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"com_1234567890abcdef05","state":"processed","source_pdfs":[{"type":"submission","id":"sub_1234567890abcdef01"},{"type":"template","id":"tpl_1234567890abcdef01","processed":false}],"metadata":{"user_id":42},"has_password":true,"delete_custom_files":false,"error_message":null,"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/combined_pdfs/combined.pdf","permanent_url":"https://app.docspring.com/combined_pdfs/com_1234567890abcdef05/files/pdf","filename":"com_1234567890abcdef05.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"actions":[],"expired":false,"expires_at":null,"processed_at":"2018-10-20T08:40:05Z","created_at":"2018-10-20T08:40:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/CombinedPdfList"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: cursor isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","details":[{"code":"not_found","message":"isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","parameter":"cursor"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Combine PDFs","tags":["Combined PDFs"],"operationId":"createCombinedPdf","description":"Merges PDFs into one: submissions, other combined PDFs, templates, custom files (POST /custom_files) and\nPDFs from URLs, in the order of `source_pdfs`. The PDF is generated in the background: on sync.api hosts the\nrequest waits for it (unless you pass `wait=false`), otherwise poll GET /combined_pdfs/{combined_pdf_id} until\n`state` isn't `pending`.\n\nA template source merges the template's processed PDF by default: the PDF submissions are filled in on,\ndecrypted and with its form fields removed. Pass `processed: false` to merge the PDF as it was uploaded.\n","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been generated before responding. Default true on sync.api hosts."}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"combined PDF created","content":{"application/json":{"examples":{"combined PDF created":{"summary":"combined PDF created","value":{"id":"com_1234567890abcdef01","state":"pending","source_pdfs":[{"type":"submission","id":"sub_1234567890abcdef01"},{"type":"template","id":"tpl_1234567890abcdef01","processed":true},{"type":"url","url":"https://example.com/terms.pdf"}],"metadata":{"user_id":42},"has_password":true,"delete_custom_files":false,"error_message":null,"files":{},"actions":[],"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"combined PDF from a combined PDF and an original template PDF":{"summary":"combined PDF from a combined PDF and an original template PDF","value":{"id":"com_1234567890abcdef01","state":"pending","source_pdfs":[{"type":"combined_pdf","id":"com_1234567890abcdef05"},{"type":"template","id":"tpl_1234567890abcdef01","template_version":"draft","processed":false},{"type":"custom_file","id":"cfi_1234567890abcdef01"}],"metadata":{},"has_password":false,"delete_custom_files":true,"error_message":null,"files":{},"actions":[],"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CombinedPdf"}}}},"422":{"description":"invalid source PDFs","content":{"application/json":{"examples":{"invalid source PDFs":{"summary":"invalid source PDFs","value":{"error":{"code":"validation_failed","message":"Invalid request: /source_pdfs/0/id isn't a submission in this account; /source_pdfs/4/id isn't a submission in this account; /source_pdfs/1/template_version isn't a published version of tpl_1234567890abcdef01 (and 1 more)","details":[{"code":"not_found","message":"isn't a submission in this account","pointer":"/source_pdfs/0/id"},{"code":"not_found","message":"isn't a submission in this account","pointer":"/source_pdfs/4/id"},{"code":"not_found","message":"isn't a published version of tpl_1234567890abcdef01","pointer":"/source_pdfs/1/template_version"},{"code":"not_found","message":"isn't a custom file in this account","pointer":"/source_pdfs/2/id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"not allowed","content":{"application/json":{"examples":{"not allowed":{"summary":"not allowed","value":{"error":{"code":"forbidden","message":"Test API tokens can't delete custom files, so delete_custom_files needs a live API token.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"not enough credits","content":{"application/json":{"examples":{"not enough credits":{"summary":"not enough credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. This combined PDF will be processed automatically once you add credits in Billing. If it's still waiting after 30 days, it won't be processed.","details":[],"request_id":"req_1234567890abcdef01","combined_pdf_id":"com_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_pdfs":{"type":"array","minItems":1,"description":"The PDFs to merge, in order.","items":{"title":"CombinedPdfSourceInput","oneOf":[{"$ref":"#/components/schemas/SubmissionSourcePdf"},{"$ref":"#/components/schemas/CombinedPdfSourcePdf"},{"$ref":"#/components/schemas/TemplateSourcePdf"},{"$ref":"#/components/schemas/CustomFileSourcePdf"},{"$ref":"#/components/schemas/UrlSourcePdf"}],"discriminator":{"propertyName":"type","mapping":{"submission":"#/components/schemas/SubmissionSourcePdf","combined_pdf":"#/components/schemas/CombinedPdfSourcePdf","template":"#/components/schemas/TemplateSourcePdf","custom_file":"#/components/schemas/CustomFileSourcePdf","url":"#/components/schemas/UrlSourcePdf"}},"x-type-description":"A PDF to merge."}},"metadata":{"type":"object","description":"Your own data about the combined PDF, such as an ID from your app."},"password":{"type":"string","minLength":1,"writeOnly":true,"description":"A password that the PDF needs to be opened with. It's never returned; `has_password` says if it's set."},"delete_custom_files":{"type":"boolean","description":"Delete the custom files in `source_pdfs` once the combined PDF has been generated (they're kept if it fails). Other combined PDFs can't use them after that. A test API token can't delete custom files."},"expires_in":{"type":"integer","minimum":1,"maximum":315360000,"writeOnly":true,"description":"Seconds after the PDF is generated until the combined PDF expires, up to 10 years (315360000). One that fails is kept for at least 48 hours. Without it, the combined PDF is kept until you delete it."}},"required":["source_pdfs"],"description":"The PDFs to merge, and the combined PDF's settings.","additionalProperties":false,"title":"CreateCombinedPdfRequest"},"examples":{"combined PDF created":{"summary":"combined PDF created","value":{"source_pdfs":[{"type":"submission","id":"sub_1234567890abcdef01"},{"type":"template","id":"tpl_1234567890abcdef01"},{"type":"url","url":"https://example.com/terms.pdf"}],"metadata":{"user_id":42},"password":"secret","expires_in":3600}},"combined PDF from a combined PDF and an original template PDF":{"summary":"combined PDF from a combined PDF and an original template PDF","value":{"source_pdfs":[{"type":"combined_pdf","id":"com_1234567890abcdef05"},{"type":"template","id":"tpl_1234567890abcdef01","template_version":"draft","processed":false},{"type":"custom_file","id":"cfi_1234567890abcdef01"}],"delete_custom_files":true}}}}},"required":true,"description":"The PDFs to merge, and the combined PDF's settings."}}},"/combined_pdfs/{combined_pdf_id}":{"get":{"summary":"Get a combined PDF","tags":["Combined PDFs"],"operationId":"getCombinedPdf","description":"Returns a combined PDF, with a temporary link to download it once it has been generated.","parameters":[{"name":"combined_pdf_id","in":"path","required":true,"schema":{"type":"string"},"description":"The combined PDF's ID.","example":"com_1234567890abcdef05"}],"responses":{"200":{"description":"combined PDF","content":{"application/json":{"examples":{"combined PDF":{"summary":"combined PDF","value":{"id":"com_1234567890abcdef05","state":"processed","source_pdfs":[{"type":"submission","id":"sub_1234567890abcdef01"},{"type":"template","id":"tpl_1234567890abcdef01","processed":false}],"metadata":{"user_id":42},"has_password":true,"delete_custom_files":false,"error_message":null,"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/combined_pdfs/combined.pdf","permanent_url":"https://app.docspring.com/combined_pdfs/com_1234567890abcdef05/files/pdf","filename":"com_1234567890abcdef05.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"actions":[],"expired":false,"expires_at":null,"processed_at":"2018-10-20T08:40:05Z","created_at":"2018-10-20T08:40:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CombinedPdf"}}}},"404":{"description":"combined PDF not found","content":{"application/json":{"examples":{"combined PDF not found":{"summary":"combined PDF not found","value":{"error":{"code":"not_found","message":"There's no combined PDF with ID com_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Expire a combined PDF","tags":["Combined PDFs"],"operationId":"expireCombinedPdf","description":"Deletes a combined PDF's PDF and returns the expired combined PDF.","parameters":[{"name":"combined_pdf_id","in":"path","required":true,"schema":{"type":"string"},"description":"The combined PDF's ID.","example":"com_1234567890abcdef05"}],"responses":{"200":{"description":"combined PDF expired","content":{"application/json":{"examples":{"combined PDF expired":{"summary":"combined PDF expired","value":{"id":"com_1234567890abcdef05","state":"processed","source_pdfs":[{"type":"submission","id":"sub_1234567890abcdef01"},{"type":"template","id":"tpl_1234567890abcdef01","processed":false}],"metadata":{},"has_password":false,"delete_custom_files":false,"error_message":null,"files":{},"actions":[],"expired":true,"expires_at":"2018-10-20T09:00:00Z","processed_at":"2018-10-20T08:40:05Z","created_at":"2018-10-20T08:40:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CombinedPdf"}}}},"403":{"description":"test API token","content":{"application/json":{"examples":{"test API token":{"summary":"test API token","value":{"error":{"code":"forbidden","message":"Test API tokens can't delete combined PDFs. Use a live API token.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"combined PDF not found","content":{"application/json":{"examples":{"combined PDF not found":{"summary":"combined PDF not found","value":{"error":{"code":"not_found","message":"There's no combined PDF with ID com_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/custom_files":{"post":{"summary":"Create a custom file from an upload","tags":["Custom Files"],"operationId":"createCustomFileFromUpload","description":"Creates a custom file from a PDF you uploaded, so you can merge it with other PDFs. Upload the file with the\npresigned upload (GET /uploads/presign) first, then pass its `fields.key` as `cache_id`.\n","externalDocs":{"url":"https://docspring.com/docs/api-guide/combine-pdfs/","description":"Learn how to merge custom files with other PDFs"},"x-uses-cached-s3-file-upload":true,"x-codegen-request-body-name":"body","parameters":[],"responses":{"201":{"description":"custom file created","content":{"application/json":{"examples":{"custom file created":{"summary":"custom file created","value":{"id":"cfi_1234567890abcdef01","download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/custom_files/cfi_1234567890abcdef01.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","size":62553,"content_type":"application/pdf","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CustomFile"}}}},"422":{"description":"invalid custom file","content":{"application/json":{"examples":{"invalid custom file":{"summary":"invalid custom file","value":{"error":{"code":"validation_failed","message":"Invalid request: /cache_id is required","details":[{"code":"required","message":"is required","pointer":"/cache_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The uploaded file to create the custom file from.","required":["cache_id"],"properties":{"cache_id":{"type":"string","minLength":1,"maxLength":255,"description":"The `fields.key` from GET /uploads/presign, after you upload the file to its URL."}},"additionalProperties":false,"title":"CreateCustomFileFromUploadRequest"},"examples":{"custom file created":{"summary":"custom file created","value":{"cache_id":"cfi_1234567890abcdef01.pdf"}}}}},"required":true,"description":"The uploaded file to create the custom file from."}},"get":{"summary":"List custom files","tags":["Custom Files"],"operationId":"listCustomFiles","description":"Returns the custom files in your account, newest first, one page at a time.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"custom files","content":{"application/json":{"examples":{"custom files":{"summary":"custom files","value":{"data":[{"id":"cfi_1234567890abcdef02","download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/custom_files/cfi_1234567890abcdef02.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","size":62553,"content_type":"application/pdf","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"cfi_1234567890abcdef01","download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/custom_files/cfi_1234567890abcdef01.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","size":62553,"content_type":"application/pdf","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/CustomFileList"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: cursor isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","details":[{"code":"not_found","message":"isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","parameter":"cursor"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/custom_files/{custom_file_id}":{"parameters":[{"name":"custom_file_id","in":"path","required":true,"schema":{"type":"string"},"description":"The custom file's ID."}],"get":{"summary":"Get a custom file","tags":["Custom Files"],"operationId":"getCustomFile","description":"Returns a custom file, with a temporary URL to download it.","responses":{"200":{"description":"custom file found","content":{"application/json":{"examples":{"custom file found":{"summary":"custom file found","value":{"id":"cfi_1234567890abcdef01","download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/custom_files/cfi_1234567890abcdef01.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","size":62553,"content_type":"application/pdf","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CustomFile"}}}},"404":{"description":"custom file not found","content":{"application/json":{"examples":{"custom file not found":{"summary":"custom file not found","value":{"error":{"code":"not_found","message":"There's no custom file with ID cfi_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a custom file","tags":["Custom Files"],"operationId":"deleteCustomFile","description":"Deletes a custom file and returns it. Use a live API token: test tokens can't delete custom files.\n","responses":{"200":{"description":"custom file deleted","content":{"application/json":{"examples":{"custom file deleted":{"summary":"custom file deleted","value":{"id":"cfi_1234567890abcdef01","download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/custom_files/cfi_1234567890abcdef01.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","size":62553,"content_type":"application/pdf","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/CustomFile"}}}},"403":{"description":"test API token","content":{"application/json":{"examples":{"test API token":{"summary":"test API token","value":{"error":{"code":"forbidden","message":"Test API tokens can't delete custom files. Use a live API token.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"custom file not found","content":{"application/json":{"examples":{"custom file not found":{"summary":"custom file not found","value":{"error":{"code":"not_found","message":"There's no custom file with ID cfi_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/folders":{"get":{"summary":"List folders","tags":["Folders"],"operationId":"listFolders","description":"Returns the folders in your account, newest first, one page at a time. Pass `parent_folder_id` to list the\nfolders in one folder.\n","parameters":[{"name":"parent_folder_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list the folders in this folder. Without it, the list has every folder, at any depth.","example":"fld_1234567890abcdef02"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50).","example":2},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one.","example":"fld_1234567890abcdef02"}],"responses":{"200":{"description":"folders in a folder","content":{"application/json":{"examples":{"folders in a folder":{"summary":"folders in a folder","value":{"data":[{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"all folders":{"summary":"all folders","value":{"data":[{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"fld_1234567890abcdef02","name":"Folder 2","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"fld_1234567890abcdef01","name":"Folder 1","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"one page of folders":{"summary":"one page of folders","value":{"data":[{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"fld_1234567890abcdef02","name":"Folder 2","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":"fld_1234567890abcdef02"}},"the next page of folders":{"summary":"the next page of folders","value":{"data":[{"id":"fld_1234567890abcdef01","name":"Folder 1","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/FolderList"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: parent_folder_id isn't a folder in this account","details":[{"code":"not_found","message":"isn't a folder in this account","parameter":"parent_folder_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a folder","tags":["Folders"],"operationId":"createFolder","description":"Creates a folder for organizing templates. Pass `parent_folder_id` to create it inside another folder.\nFolder names are unique within their parent folder.\n","x-codegen-request-body-name":"body","parameters":[],"responses":{"201":{"description":"folder created inside another folder","content":{"application/json":{"examples":{"folder created inside another folder":{"summary":"folder created inside another folder","value":{"id":"fld_1234567890abcdef05","name":"Folder 3","path":"/Folder 1","parent_folder_id":"fld_1234567890abcdef01","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"folder created at the root":{"summary":"folder created at the root","value":{"id":"fld_1234567890abcdef05","name":"Folder 3","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Folder"}}}},"422":{"description":"invalid folder","content":{"application/json":{"examples":{"invalid folder":{"summary":"invalid folder","value":{"error":{"code":"validation_failed","message":"Invalid request: /name is already the name of a folder in this folder. Choose another name","details":[{"code":"invalid","message":"is already the name of a folder in this folder. Choose another name","pointer":"/name"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/]*$","description":"The folder's name. It can't contain `/`, and is unique within its parent folder.","x-pattern-message":"can't contain a slash (/)"},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder this folder is in. Null for a folder at the root."}},"required":["name"],"description":"The folder to create.","additionalProperties":false,"title":"CreateFolderRequest"},"examples":{"folder created inside another folder":{"summary":"folder created inside another folder","value":{"name":"Folder 3","parent_folder_id":"fld_1234567890abcdef01"}},"folder created at the root":{"summary":"folder created at the root","value":{"name":"Folder 3"}}}}},"required":true,"description":"The folder to create."}}},"/folders/{folder_id}":{"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"},"description":"The folder's ID."}],"get":{"summary":"Get a folder","tags":["Folders"],"operationId":"getFolder","description":"Returns a folder.","responses":{"200":{"description":"folder found","content":{"application/json":{"examples":{"folder found":{"summary":"folder found","value":{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Folder"}}}},"404":{"description":"folder not found","content":{"application/json":{"examples":{"folder not found":{"summary":"folder not found","value":{"error":{"code":"not_found","message":"There's no folder with ID fld_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a folder","tags":["Folders"],"operationId":"deleteFolder","description":"Deletes an empty folder and returns it. A folder that still has templates or folders in it can't be deleted.\n","responses":{"200":{"description":"folder deleted","content":{"application/json":{"examples":{"folder deleted":{"summary":"folder deleted","value":{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Folder"}}}},"409":{"description":"folder is not empty","content":{"application/json":{"examples":{"folder is not empty":{"summary":"folder is not empty","value":{"error":{"code":"conflict","message":"The folder isn't empty. Move or delete its contents first.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"folder not found","content":{"application/json":{"examples":{"folder not found":{"summary":"folder not found","value":{"error":{"code":"not_found","message":"There's no folder with ID fld_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/folders/{folder_id}/move":{"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"},"description":"The folder's ID."}],"post":{"summary":"Move a folder","tags":["Folders"],"operationId":"moveFolder","description":"Moves a folder into another folder, or to the root with `parent_folder_id: null`. Its templates and folders\nmove with it. A folder can't move into itself or one of its own folders.\n","x-codegen-request-body-name":"body","parameters":[],"responses":{"200":{"description":"folder moved into another folder","content":{"application/json":{"examples":{"folder moved into another folder":{"summary":"folder moved into another folder","value":{"id":"fld_1234567890abcdef01","name":"Folder 1","path":"/Folder 2","parent_folder_id":"fld_1234567890abcdef02","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"folder moved to the root":{"summary":"folder moved to the root","value":{"id":"fld_1234567890abcdef03","name":"nested folder 1","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Folder"}}}},"422":{"description":"invalid move","content":{"application/json":{"examples":{"invalid move":{"summary":"invalid move","value":{"error":{"code":"validation_failed","message":"Invalid request: /parent_folder_id is required","details":[{"code":"required","message":"is required","pointer":"/parent_folder_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"folder not found","content":{"application/json":{"examples":{"folder not found":{"summary":"folder not found","value":{"error":{"code":"not_found","message":"There's no folder with ID fld_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder this folder is in. Null for a folder at the root."}},"required":["parent_folder_id"],"description":"Where to move the folder.","additionalProperties":false,"title":"MoveFolderRequest"},"examples":{"folder moved into another folder":{"summary":"folder moved into another folder","value":{"parent_folder_id":"fld_1234567890abcdef02"}},"folder moved to the root":{"summary":"folder moved to the root","value":{"parent_folder_id":null}}}}},"required":true,"description":"Where to move the folder."}}},"/folders/{folder_id}/rename":{"parameters":[{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"},"description":"The folder's ID."}],"post":{"summary":"Rename a folder","tags":["Folders"],"operationId":"renameFolder","description":"Renames a folder. The name must be unique within its parent folder.\n","x-codegen-request-body-name":"body","parameters":[],"responses":{"200":{"description":"folder renamed","content":{"application/json":{"examples":{"folder renamed":{"summary":"folder renamed","value":{"id":"fld_1234567890abcdef01","name":"Folder 3","path":"/","parent_folder_id":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Folder"}}}},"422":{"description":"name already exists","content":{"application/json":{"examples":{"name already exists":{"summary":"name already exists","value":{"error":{"code":"validation_failed","message":"Invalid request: /name is already the name of a folder in this folder. Choose another name","details":[{"code":"invalid","message":"is already the name of a folder in this folder. Choose another name","pointer":"/name"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"folder not found","content":{"application/json":{"examples":{"folder not found":{"summary":"folder not found","value":{"error":{"code":"not_found","message":"There's no folder with ID fld_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/]*$","description":"The folder's name. It can't contain `/`, and is unique within its parent folder.","x-pattern-message":"can't contain a slash (/)"}},"required":["name"],"description":"The folder's new name.","additionalProperties":false,"title":"RenameFolderRequest"},"examples":{"folder renamed":{"summary":"folder renamed","value":{"name":"Folder 3"}}}}},"required":true,"description":"The folder's new name."}}},"/signature_requests/{signature_request_id}":{"get":{"summary":"Get a signature request","tags":["Signature Requests"],"operationId":"getSignatureRequest","description":"Returns a signature request, with the values the person has entered so far.","parameters":[{"name":"signature_request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The signature request's ID.","example":"srq_1234567890abcdef01"}],"responses":{"200":{"description":"signature request","content":{"application/json":{"examples":{"signature request":{"summary":"signature request","value":{"id":"srq_1234567890abcdef01","submission_id":"sub_1234567890abcdef01","name":"John Smith","email":"john@example.com","fields":["last_name"],"metadata":{"user_id":42},"role":"Signer 1","sort_order":0,"state":"pending","data":{"last_name":"Smith"},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SignatureRequest"}}}},"404":{"description":"signature request not found","content":{"application/json":{"examples":{"signature request not found":{"summary":"signature request not found","value":{"error":{"code":"not_found","message":"There's no signature request with ID srq_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a signature request","tags":["Signature Requests"],"operationId":"updateSignatureRequest","description":"Changes a pending signature request's metadata, or how your app authenticated the person (for the audit trail).\nOnce the person has opened it, only its metadata can be changed, and a completed or declined signature\nrequest can't be changed.\n","parameters":[{"name":"signature_request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The signature request's ID.","example":"srq_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"200":{"description":"signature request updated","content":{"application/json":{"examples":{"signature request updated":{"summary":"signature request updated","value":{"id":"srq_1234567890abcdef01","submission_id":"sub_1234567890abcdef01","name":"John Smith","email":"john@example.com","fields":["last_name"],"metadata":{"user_id":43},"role":"Signer 1","sort_order":0,"state":"pending","data":{"last_name":"Smith"},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"oauth","auth_second_factor_type":"none","auth_provider":"google","auth_session_started_at":"2018-10-20T08:00:00Z","auth_session_id_hash":null,"auth_user_id_hash":"8ae0e445664ca53407906db8638d8ba07a2383f656383a4427bed1ab645ca29a","auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SignatureRequest"}}}},"409":{"description":"signature request completed","content":{"application/json":{"examples":{"signature request completed":{"summary":"signature request completed","value":{"error":{"code":"conflict","message":"Signature requests can't be changed after they've been completed.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid request","content":{"application/json":{"examples":{"invalid request":{"summary":"invalid request","value":{"error":{"code":"validation_failed","message":"Invalid request: /auth_type must be one of: \"password\", \"oauth\", \"email_link\", \"phone_number\", \"ldap\", \"saml\"; /name isn't a documented property","details":[{"code":"enum","message":"must be one of: \"password\", \"oauth\", \"email_link\", \"phone_number\", \"ldap\", \"saml\"","pointer":"/auth_type"},{"code":"unknown_property","message":"isn't a documented property","pointer":"/name"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"signature request not found","content":{"application/json":{"examples":{"signature request not found":{"summary":"signature request not found","value":{"error":{"code":"not_found","message":"There's no signature request with ID srq_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","description":"Your own data about the signature request, such as an ID from your app."},"auth_type":{"title":"SignatureRequestAuthType","type":"string","description":"How your app authenticated the person before it showed them the signature request.","x-type-description":"How your app authenticated a person before it showed them a signature request.","enum":["password","oauth","email_link","phone_number","ldap","saml"]},"auth_second_factor_type":{"title":"SignatureRequestAuthSecondFactorType","type":"string","description":"The second factor your app authenticated them with, if any.","x-type-description":"A second factor your app authenticated a person with.","enum":["none","phone_number","totp","mobile_push","security_key","fingerprint"]},"auth_provider":{"type":["string","null"],"maxLength":255,"description":"The service that authenticated them, such as `google`. Required when `auth_type` is `oauth`."},"auth_session_started_at":{"type":["string","null"],"format":"date-time","description":"When your app authenticated them. Set for you with `email_link`."},"auth_session_id_hash":{"type":["string","null"],"description":"A hash of your app's session ID, for the audit trail."},"auth_user_id_hash":{"type":["string","null"],"description":"Their user ID in your app, or a SHA-256 hash of a salt and the user ID."},"auth_username_hash":{"type":["string","null"],"description":"Their username in your app, or a SHA-256 hash of a salt and the username."},"auth_phone_number_hash":{"type":["string","null"],"description":"The phone number they authenticated with, or a SHA-256 hash of a salt and the phone number."}},"description":"The settings to change. Properties left out keep their values.","additionalProperties":false,"title":"UpdateSignatureRequestRequest"},"examples":{"signature request updated":{"summary":"signature request updated","value":{"metadata":{"user_id":43},"auth_type":"oauth","auth_provider":"google","auth_session_started_at":"2018-10-20T08:00:00Z","auth_user_id_hash":"8ae0e445664ca53407906db8638d8ba07a2383f656383a4427bed1ab645ca29a"}}}}},"required":true,"description":"The settings to change. Properties left out keep their values."}}},"/signature_requests/{signature_request_id}/tokens":{"post":{"summary":"Create a signature request token","tags":["Signature Requests"],"operationId":"createSignatureRequestToken","description":"Creates a token that opens the signature request without signing in, in a form embedded in your app or from a\nlink you send. The response is the only time the token's secret is returned. The link works for 24 hours, or\n7 days for an `email` token, and a signing page that opened in time keeps working for 7 more days. A test API\ntoken can't create a token for a live signature request.\n","parameters":[{"name":"signature_request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The signature request's ID.","example":"srq_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"token created","content":{"application/json":{"examples":{"token created":{"summary":"token created","value":{"id":"1234567890abcdef01","signature_request_id":"srq_1234567890abcdef01","type":"email","secret":"ABCDEF01234567890","signature_request_url":"https://app.docspring.com/signature_requests/srq_1234567890abcdef01?token_id=1234567890abcdef01&token_secret=ABCDEF01234567890","expires_at":"2018-10-27T09:00:00Z","created_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SignatureRequestToken"}}}},"403":{"description":"test API token on a live signature request","content":{"application/json":{"examples":{"test API token on a live signature request":{"summary":"test API token on a live signature request","value":{"error":{"code":"forbidden","message":"You must use a live API token to create a token for a live signature request.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"signature request finished","content":{"application/json":{"examples":{"signature request finished":{"summary":"signature request finished","value":{"error":{"code":"conflict","message":"The signature request has already been completed, so it can't have a new token.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid token request","content":{"application/json":{"examples":{"invalid token request":{"summary":"invalid token request","value":{"error":{"code":"validation_failed","message":"Invalid request: /kind isn't a documented property","details":[{"code":"unknown_property","message":"isn't a documented property","pointer":"/kind"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"signature request not found","content":{"application/json":{"examples":{"signature request not found":{"summary":"signature request not found","value":{"error":{"code":"not_found","message":"There's no signature request with ID srq_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The kind of link to make. Send no body for an `api` token.","properties":{"type":{"title":"SignatureRequestTokenType","x-type-description":"How long a signature request token's link opens the signature request.","type":"string","enum":["api","email"],"description":"`api` (the default): the link opens the signature request for 24 hours, for a form your app opens or a link it gives the person right away. `email`: 7 days, for a link you send by email."}},"additionalProperties":false,"title":"CreateSignatureRequestTokenRequest"},"examples":{"token created":{"summary":"token created","value":{"type":"email"}},"token created with no body":{"summary":"token created with no body","value":{}}}}},"description":"The kind of link to make. Send no body for an `api` token."}}},"/signature_requests/{signature_request_id}/events":{"post":{"summary":"Record a signature request event","tags":["Signature Requests"],"operationId":"createSignatureRequestEvent","description":"Records something that happened outside DocSpring in the signature request's audit trail: you sent the request\nto the person (`send_request`). The audit trail shows it as reported by your account.\n","parameters":[{"name":"signature_request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The signature request's ID.","example":"srq_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"event recorded","content":{"application/json":{"examples":{"event recorded":{"summary":"event recorded","value":{"id":"dre_1234567890abcdef01","submission_id":"sub_1234567890abcdef01","signature_request_id":"srq_1234567890abcdef01","event_type":"send_request","message_type":"email","message_recipient":"john@example.com","occurred_at":"2018-10-20T08:59:00Z","created_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SignatureRequestEvent"}}}},"422":{"description":"invalid event","content":{"application/json":{"examples":{"invalid event":{"summary":"invalid event","value":{"error":{"code":"validation_failed","message":"Invalid request: /message_type is required when event_type is send_request; /message_recipient is required when event_type is send_request","details":[{"code":"required","message":"is required when event_type is send_request","pointer":"/message_type"},{"code":"required","message":"is required when event_type is send_request","pointer":"/message_recipient"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"signature request not found","content":{"application/json":{"examples":{"signature request not found":{"summary":"signature request not found","value":{"error":{"code":"not_found","message":"There's no signature request with ID srq_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"title":"SignatureRequestEventType","x-type-description":"Something that happened to a signature request outside DocSpring.","type":"string","enum":["send_request"],"description":"`send_request`: you sent the signature request to the person (`message_type` and `message_recipient` are required). It's the only event the API records: DocSpring records everything that happens in the signing form itself, and people decline a signature request in its form."},"message_type":{"title":"SignatureRequestMessageType","type":["string","null"],"description":"How you sent the request. Required for `send_request`.","x-type-description":"How a signature request was sent to a person.","enum":["email","sms","fax","mail","slack","msteams","discord","telegram","whatsapp",null]},"message_recipient":{"type":["string","null"],"maxLength":255,"description":"Where you sent the request, such as an email address or a phone number. Required for `send_request`."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened. Default now."}},"required":["event_type"],"description":"The event to record.","additionalProperties":false,"title":"CreateSignatureRequestEventRequest"},"examples":{"event recorded":{"summary":"event recorded","value":{"event_type":"send_request","message_type":"email","message_recipient":"john@example.com","occurred_at":"2018-10-20T08:59:00Z"}}}}},"required":true,"description":"The event to record."}}},"/submissions/batches":{"post":{"summary":"Generate PDFs in a batch","tags":["Submissions"],"operationId":"createSubmissionBatch","description":"Creates up to 50 submissions in one request, from one template or several. The PDFs are only generated when\nevery submission is valid. On sync.api hosts the request waits until every PDF has been generated (unless you\npass `wait=false`), otherwise poll GET /submissions/batches/{submission_batch_id} until `processed_at` is set.\n\nWhen any submission is invalid, nothing is generated and the request returns a 422. Submissions whose data\ndoesn't match their template's fields are still saved with their errors (an `invalid_data` error, with each\none's `submission_id` in its details), so you can find them in DocSpring. The other submissions aren't saved.\n","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until every PDF in the batch has been generated before responding. Default true on sync.api hosts."}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"batch created","content":{"application/json":{"examples":{"batch created":{"summary":"batch created","value":{"id":"sbb_1234567890abcdef01","state":"pending","metadata":{"job_id":54321},"total_count":2,"pending_count":2,"error_count":0,"completion_percentage":0,"submissions":[{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef01","source":"api","state":"pending","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{"row":1},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef02","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef01","source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{"row":2},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"batch with several templates":{"summary":"batch with several templates","value":{"id":"sbb_1234567890abcdef01","state":"pending","metadata":{},"total_count":3,"pending_count":3,"error_count":0,"completion_percentage":0,"submissions":[{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef01","source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef02","template_id":"tpl_1234567890abcdef02","template_type":"html","template_version":null,"batch_id":"sbb_1234567890abcdef01","source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef03","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef01","source":"api","state":"pending","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":true,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SubmissionBatch"}}}},"422":{"description":"invalid data","content":{"application/json":{"examples":{"invalid data":{"summary":"invalid data","value":{"error":{"code":"invalid_data","message":"No PDFs were generated: 2 of 3 submissions are invalid: /submissions/1/data/last_name is required; /submissions/2/data/phone_number must be a string or null","details":[{"code":"required","message":"is required","pointer":"/submissions/1/data/last_name","submission_id":"sub_1234567890abcdef01"},{"code":"type","message":"must be a string or null","pointer":"/submissions/2/data/phone_number","submission_id":"sub_1234567890abcdef02"}],"request_id":"req_1234567890abcdef01","submission_batch_id":"sbb_1234567890abcdef01"}}},"empty data and unknown field overrides":{"summary":"empty data and unknown field overrides","value":{"error":{"code":"invalid_data","message":"No PDFs were generated: 2 of 2 submissions are invalid: /submissions/0/data/first_name is required; /submissions/0/data/last_name is required; /submissions/1/field_overrides/middle_name isn't a field of this template","details":[{"code":"required","message":"is required","pointer":"/submissions/0/data/first_name","submission_id":"sub_1234567890abcdef01"},{"code":"required","message":"is required","pointer":"/submissions/0/data/last_name","submission_id":"sub_1234567890abcdef01"},{"code":"not_found","message":"isn't a field of this template","pointer":"/submissions/1/field_overrides/middle_name","submission_id":"sub_1234567890abcdef02"}],"request_id":"req_1234567890abcdef01","submission_batch_id":"sbb_1234567890abcdef01"}}},"invalid request":{"summary":"invalid request","value":{"error":{"code":"validation_failed","message":"Invalid request: /template_version isn't a published version of tpl_1234567890abcdef01; /submissions/2/template_id isn't a template in this account","details":[{"code":"not_found","message":"isn't a published version of tpl_1234567890abcdef01","pointer":"/template_version"},{"code":"not_found","message":"isn't a template in this account","pointer":"/submissions/2/template_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"not enough credits","content":{"application/json":{"examples":{"not enough credits":{"summary":"not enough credits","value":{"error":{"code":"insufficient_credits","message":"Your credit balance can't cover some of this batch's live submissions. Those submissions wait in the insufficient_credits state, and each one's error_message says whether it's generated once you add credits in Billing.","details":[],"request_id":"req_1234567890abcdef01","submission_batch_id":"sbb_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"account suspended","content":{"application/json":{"examples":{"account suspended":{"summary":"account suspended","value":{"error":{"code":"account_suspended","message":"This DocSpring account is suspended, so it can't create submissions or combined PDFs. Reactivate it on the Billing page.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","description":"Your own data about the batch, such as an ID from your app."},"template_id":{"type":"string","description":"The template for each submission that doesn't name its own `template_id`."},"template_version":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","description":"The template version to use: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published).","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"test":{"type":"boolean","description":"The default `test` for each submission that doesn't set its own."},"submissions":{"type":"array","minItems":1,"maxItems":50,"description":"Up to 50 submissions. Each one takes the properties of POST /templates/{template_id}/submissions except `signature_requests`, plus `template_id` and `template_version` when it uses a different template from the batch.","items":{"type":"object","properties":{"test":{"type":"boolean","description":"Test PDFs have a watermark and are free. Live PDFs use credits. Submissions made with a test API token are always test submissions."},"editable":{"type":"boolean","description":"`true` keeps the PDF's text and check fields fillable, and `false` flattens every field. Left out, the template decides: its `editable_submissions` setting, or each field's own Editable option. A response shows the template's setting when the request left this out. Can't be `true` with `signature_requests`."},"data":{"type":"object","description":"The values of the template's fields, by field name. Required for a PDF template."},"metadata":{"type":"object","description":"Your own data about the submission, such as an ID from your app. It isn't printed on the PDF."},"password":{"type":"string","minLength":1,"writeOnly":true,"description":"A password that the PDF needs to be opened with. It's never returned; `has_password` says if it's set."},"expires_in":{"type":"integer","minimum":1,"maximum":315360000,"writeOnly":true,"description":"Seconds after the PDF is generated until the submission expires, up to 10 years (315360000). Default the template's expiration setting. A submission that isn't processed, such as one with invalid data, is kept for at least 48 hours."},"field_overrides":{"type":"object","writeOnly":true,"description":"Changes to field settings for this submission only, by field name, such as `{\"name\": {\"required\": false, \"font_size\": 9}}`. A setting that identifies the field (`id`, `name`, `type`), that only the template sets (such as `description`), or that doesn't apply to the field's type and display type (such as `check_character` on a field displayed as text) is a 422. With `signature_requests`, `editable: true` is a 422, and a `default` for a signature or initials field makes the submission `invalid_data`.","additionalProperties":{"$ref":"#/components/schemas/FieldOverride"}},"html":{"type":"string","writeOnly":true,"description":"For an HTML template, HTML to use instead of the template's."},"css":{"type":"string","writeOnly":true,"description":"For an HTML template, CSS to use instead of the template's."},"template_id":{"type":"string","description":"The submission's template. Default the batch's `template_id`."},"template_version":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","description":"The version of the submission's template. Default the batch's `template_version`.","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"}},"title":"SubmissionInput","x-type-description":"A submission to create in a batch, with its own template when it doesn't use the batch's.","additionalProperties":false}}},"required":["submissions"],"description":"The submissions to create, and the settings they share.","additionalProperties":false,"title":"CreateSubmissionBatchRequest"},"examples":{"batch created":{"summary":"batch created","value":{"template_id":"tpl_1234567890abcdef01","metadata":{"job_id":54321},"submissions":[{"data":{"first_name":"John","last_name":"Smith"},"metadata":{"row":1}},{"data":{"first_name":"Jane","last_name":"Doe"},"test":true,"metadata":{"row":2}}]}},"batch with several templates":{"summary":"batch with several templates","value":{"template_id":"tpl_1234567890abcdef01","test":true,"submissions":[{"data":{"first_name":"John","last_name":"Smith"}},{"template_id":"tpl_1234567890abcdef02","data":{"invoice_number":"INV-1"},"html":"<p>{{ invoice_number }}</p>"},{"data":{"first_name":"Jane","last_name":"Doe"},"template_version":"draft","test":false,"expires_in":3600,"password":"secret"}]}}}}},"required":true,"description":"The submissions to create, and the settings they share."}}},"/submissions/batches/{submission_batch_id}":{"get":{"summary":"Get a batch","tags":["Submissions"],"operationId":"getSubmissionBatch","description":"Returns a batch with its submissions. The batch has finished once `processed_at` is set: its `state` is\n`processed` when every PDF was generated, or `error` when any submission failed.\n","parameters":[{"name":"submission_batch_id","in":"path","required":true,"schema":{"type":"string"},"description":"The batch's ID.","example":"sbb_1234567890abcdef05"},{"name":"include_data","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include each submission's `data` (null without it).","example":true}],"responses":{"200":{"description":"batch","content":{"application/json":{"examples":{"batch":{"summary":"batch","value":{"id":"sbb_1234567890abcdef05","state":"pending","metadata":{"job_id":54321},"total_count":2,"pending_count":1,"error_count":0,"completion_percentage":50,"submissions":[{"id":"sub_1234567890abcdef07","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef05","source":"api","state":"processed","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef06","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef05","source":"api","state":"pending","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"processed_at":null,"created_at":"2018-10-20T08:59:00Z","updated_at":"2018-10-20T09:00:00Z"}},"batch with its submissions' data":{"summary":"batch with its submissions' data","value":{"id":"sbb_1234567890abcdef05","state":"pending","metadata":{"job_id":54321},"total_count":2,"pending_count":1,"error_count":0,"completion_percentage":50,"submissions":[{"id":"sub_1234567890abcdef07","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef05","source":"api","state":"processed","test":false,"editable":false,"data":{"first_name":"John","last_name":"Smith"},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef06","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":"sbb_1234567890abcdef05","source":"api","state":"pending","test":false,"editable":false,"data":{"first_name":"Jane","last_name":"Doe"},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"processed_at":null,"created_at":"2018-10-20T08:59:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/SubmissionBatch"}}}},"404":{"description":"batch not found","content":{"application/json":{"examples":{"batch not found":{"summary":"batch not found","value":{"error":{"code":"not_found","message":"There's no submission batch with ID sbb_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/submissions":{"get":{"summary":"List submissions","tags":["Submissions"],"operationId":"listSubmissions","description":"Returns the submissions in your account, newest first, one page at a time. Lists leave out each submission's\n`data` unless you pass `include_data=true`.\n","parameters":[{"name":"template_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list this template's submissions.","example":"tpl_1234567890abcdef01"},{"name":"test","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only list test submissions (true) or live submissions (false).","example":false},{"name":"created_after","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only list submissions created after this time (RFC 3339, such as `2025-01-31T09:00:00Z`).","example":"2018-10-20T08:40:00Z"},{"name":"created_before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only list submissions created before this time.","example":"2018-10-20T09:00:00Z"},{"name":"include_data","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include each submission's `data` (null without it).","example":true},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"submissions","content":{"application/json":{"examples":{"submissions":{"summary":"submissions","value":{"data":[{"id":"sub_1234567890abcdef02","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T08:45:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"processed","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{"user_id":42},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/submissions/submission.pdf","permanent_url":"https://app.docspring.com/submissions/sub_1234567890abcdef01/files/pdf","filename":"sub_1234567890abcdef01.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"preview_generated_at":null,"expired":false,"expires_at":"2018-10-27T09:00:00Z","processed_at":"2018-10-20T08:30:05Z","created_at":"2018-10-20T08:30:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"live submissions with their data":{"summary":"live submissions with their data","value":{"data":[{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"processed","test":false,"editable":false,"data":{"first_name":"John","last_name":"Smith","phone_number":"+11234567890"},"data_errors":[],"error_message":null,"metadata":{"user_id":42},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/submissions/submission.pdf","permanent_url":"https://app.docspring.com/submissions/sub_1234567890abcdef01/files/pdf","filename":"sub_1234567890abcdef01.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"preview_generated_at":null,"expired":false,"expires_at":"2018-10-27T09:00:00Z","processed_at":"2018-10-20T08:30:05Z","created_at":"2018-10-20T08:30:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"submissions created in a time range":{"summary":"submissions created in a time range","value":{"data":[{"id":"sub_1234567890abcdef02","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T08:45:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/SubmissionList"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: template_id isn't a template in this account","details":[{"code":"not_found","message":"isn't a template in this account","parameter":"template_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/templates/{template_id}/submissions":{"get":{"summary":"List a template's submissions","tags":["Submissions"],"operationId":"listTemplateSubmissions","description":"Returns a template's submissions (from every version of the template), newest first.","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"test","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only list test submissions (true) or live submissions (false)."},{"name":"created_after","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only list submissions created after this time (RFC 3339, such as `2025-01-31T09:00:00Z`)."},{"name":"created_before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only list submissions created before this time."},{"name":"include_data","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include each submission's `data` (null without it)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"template's submissions","content":{"application/json":{"examples":{"template's submissions":{"summary":"template's submissions","value":{"data":[{"id":"sub_1234567890abcdef02","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"pending","test":true,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T08:45:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"processed","test":false,"editable":false,"data":null,"data_errors":[],"error_message":null,"metadata":{"user_id":42},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":null,"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/submissions/submission.pdf","permanent_url":"https://app.docspring.com/submissions/sub_1234567890abcdef01/files/pdf","filename":"sub_1234567890abcdef01.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"preview_generated_at":null,"expired":false,"expires_at":"2018-10-27T09:00:00Z","processed_at":"2018-10-20T08:30:05Z","created_at":"2018-10-20T08:30:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/SubmissionList"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: cursor isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","details":[{"code":"not_found","message":"isn't an ID in this list. Pass the previous page's next_cursor. A cursor stops working once its record is deleted or no longer matches the list's filters, so get the next page before you delete or change the records on this one","parameter":"cursor"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Generate a PDF","tags":["Submissions"],"operationId":"createSubmission","description":"Creates a submission: fills in a template with your data and generates a PDF. The PDF is generated in the\nbackground: on sync.api hosts the request waits for it (unless you pass `wait=false`), otherwise poll GET\n/submissions/{submission_id} until `state` isn't `pending`.\n\nData that doesn't match the template's fields returns a 422 with an `invalid_data` error. The submission\nis still saved, with its errors, so you can find it in DocSpring: the error's `submission_id` is its ID.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"description":"The template version to use: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published)."},{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been generated before responding. Default true on sync.api hosts."}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"submission created","content":{"application/json":{"examples":{"submission created":{"summary":"submission created","value":{"id":"sub_1234567890abcdef04","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"pending","test":true,"editable":false,"data":{"first_name":"John","last_name":"Smith","phone_number":"+11234567890"},"data_errors":[],"error_message":null,"metadata":{"user_id":42},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"submission with signature requests created":{"summary":"submission with signature requests created","value":{"id":"sub_1234567890abcdef04","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"waiting_for_signature_requests","test":false,"editable":false,"data":{"phone_number":"+11234567890"},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[{"id":"srq_1234567890abcdef04","submission_id":"sub_1234567890abcdef04","name":"John Smith","email":"john@example.com","fields":["first_name","last_name"],"metadata":{},"role":"Signer 1","sort_order":0,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"signature requests for some of the signers":{"summary":"signature requests for some of the signers","value":{"id":"sub_1234567890abcdef04","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"waiting_for_signature_requests","test":false,"editable":false,"data":{},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[{"id":"srq_1234567890abcdef05","submission_id":"sub_1234567890abcdef04","name":"John Smith","email":null,"fields":["first_name"],"metadata":{},"role":"Signer 2","sort_order":1,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"srq_1234567890abcdef04","submission_id":"sub_1234567890abcdef04","name":"Jane Smith","email":null,"fields":["last_name"],"metadata":{},"role":"Signer 3","sort_order":2,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}},"signature requests with a shared field list and an editable prefilled value":{"summary":"signature requests with a shared field list and an editable prefilled value","value":{"id":"sub_1234567890abcdef04","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"waiting_for_signature_requests","test":false,"editable":false,"data":{"first_name":"John"},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[{"id":"srq_1234567890abcdef04","submission_id":"sub_1234567890abcdef04","name":"Jane Smith","email":null,"fields":["last_name"],"metadata":{},"role":"Signer 1","sort_order":0,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"srq_1234567890abcdef05","submission_id":"sub_1234567890abcdef04","name":"John Smith","email":null,"fields":["first_name"],"metadata":{},"role":"Signer 2","sort_order":1,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":null,"processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Submission"}}}},"422":{"description":"invalid data","content":{"application/json":{"examples":{"invalid data":{"summary":"invalid data","value":{"error":{"code":"invalid_data","message":"The data doesn't match the template's fields: /data/phone_number must be a string or null; /data/last_name is required","details":[{"code":"type","message":"must be a string or null","pointer":"/data/phone_number"},{"code":"required","message":"is required","pointer":"/data/last_name"}],"request_id":"req_1234567890abcdef01","submission_id":"sub_1234567890abcdef04"}}},"invalid request":{"summary":"invalid request","value":{"error":{"code":"validation_failed","message":"Invalid request: /html is only for HTML templates","details":[{"code":"not_allowed","message":"is only for HTML templates","pointer":"/html"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"not enough credits","content":{"application/json":{"examples":{"not enough credits":{"summary":"not enough credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. This submission will be processed automatically once you add credits in Billing. If it's still waiting after 30 days, it won't be processed.","details":[],"request_id":"req_1234567890abcdef01","submission_id":"sub_1234567890abcdef04"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"the account is suspended","content":{"application/json":{"examples":{"the account is suspended":{"summary":"the account is suspended","value":{"error":{"code":"account_suspended","message":"This DocSpring account is suspended, so it can't create submissions or combined PDFs. Reactivate it on the Billing page.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"boolean","description":"Test PDFs have a watermark and are free. Live PDFs use credits. Submissions made with a test API token are always test submissions."},"editable":{"type":"boolean","description":"`true` keeps the PDF's text and check fields fillable, and `false` flattens every field. Left out, the template decides: its `editable_submissions` setting, or each field's own Editable option. A response shows the template's setting when the request left this out. Can't be `true` with `signature_requests`."},"data":{"type":"object","description":"The values of the template's fields, by field name. Required for a PDF template, unless `signature_requests` collects the values."},"metadata":{"type":"object","description":"Your own data about the submission, such as an ID from your app. It isn't printed on the PDF."},"password":{"type":"string","minLength":1,"writeOnly":true,"description":"A password that the PDF needs to be opened with. It's never returned; `has_password` says if it's set."},"expires_in":{"type":"integer","minimum":1,"maximum":315360000,"writeOnly":true,"description":"Seconds after the PDF is generated until the submission expires, up to 10 years (315360000). Default the template's expiration setting. A submission that isn't processed, such as one with invalid data, is kept for at least 48 hours."},"field_overrides":{"type":"object","writeOnly":true,"description":"Changes to field settings for this submission only, by field name, such as `{\"name\": {\"required\": false, \"font_size\": 9}}`. A setting that identifies the field (`id`, `name`, `type`), that only the template sets (such as `description`), or that doesn't apply to the field's type and display type (such as `check_character` on a field displayed as text) is a 422. With `signature_requests`, `editable: true` is a 422, and a `default` for a signature or initials field makes the submission `invalid_data`.","additionalProperties":{"$ref":"#/components/schemas/FieldOverride"}},"html":{"type":"string","writeOnly":true,"description":"For an HTML template, HTML to use instead of the template's."},"css":{"type":"string","writeOnly":true,"description":"For an HTML template, CSS to use instead of the template's."},"signature_requests":{"type":"array","maxItems":100,"description":"The people who sign the PDF, and fill in their fields first. The PDF is generated once every signature request is completed. PDF templates only. Without `role`s, the first signature request is `Signer 1`, the second `Signer 2`, and so on. To leave a signer out, give every signature request its `role` and leave that one's out. Only the signers sign: a value for a signature or initials field in `data` makes the submission `invalid_data`.","items":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"The name of the person the request is for."},"email":{"type":["string","null"],"maxLength":255,"description":"Their email address."},"fields":{"type":"array","minItems":1,"uniqueItems":true,"description":"The fields this person fills in. Each field can only be in one signature request, and a field that `data` fills in needs `prefilled_values_editable`.","items":{"type":"string","minLength":1}},"metadata":{"type":"object","description":"Your own data about the signature request, such as an ID from your app."},"role":{"type":"string","minLength":1,"description":"Which of the template's signers the person is: `Signer 1`, `Signer 2` and so on, up to `Signer 100`, until templates have roles of their own. Either every signature request has a `role` or none does, and each role can only have one."},"auth_type":{"title":"SignatureRequestAuthType","type":"string","description":"How your app authenticated the person before it showed them the signature request.","x-type-description":"How your app authenticated a person before it showed them a signature request.","enum":["password","oauth","email_link","phone_number","ldap","saml"]},"auth_second_factor_type":{"title":"SignatureRequestAuthSecondFactorType","type":"string","description":"The second factor your app authenticated them with, if any.","x-type-description":"A second factor your app authenticated a person with.","enum":["none","phone_number","totp","mobile_push","security_key","fingerprint"]},"auth_provider":{"type":["string","null"],"maxLength":255,"description":"The service that authenticated them, such as `google`. Required when `auth_type` is `oauth`."},"auth_session_started_at":{"type":["string","null"],"format":"date-time","description":"When your app authenticated them. Set for you with `email_link`."},"auth_session_id_hash":{"type":["string","null"],"description":"A hash of your app's session ID, for the audit trail."},"auth_user_id_hash":{"type":["string","null"],"description":"Their user ID in your app, or a SHA-256 hash of a salt and the user ID."},"auth_username_hash":{"type":["string","null"],"description":"Their username in your app, or a SHA-256 hash of a salt and the username."},"auth_phone_number_hash":{"type":["string","null"],"description":"The phone number they authenticated with, or a SHA-256 hash of a salt and the phone number."},"ignore_unknown_fields":{"type":"boolean","description":"Leave out names in `fields` that the template doesn't have, for one field list that you send with several templates. Without it, an unknown name makes the submission `invalid_data`."},"prefilled_values_editable":{"type":"boolean","description":"Let the person change the values that `data` already has for fields in `fields`. Without it, those fields are a 422."}},"title":"SignatureRequestInput","required":["fields","auth_type"],"x-type-description":"A request for someone to fill in their fields of a submission and sign it. Someone who only fills in fields for the people who sign later (such as an employer's section) has a signature request too. The submission's PDF is generated once every signature request is completed.","additionalProperties":false}}},"description":"The submission's data and settings.","additionalProperties":false,"title":"CreateSubmissionRequest"},"examples":{"submission created":{"summary":"submission created","value":{"data":{"first_name":"John","last_name":"Smith","phone_number":"+11234567890"},"metadata":{"user_id":42},"test":true}},"submission with field settings overridden":{"summary":"submission with field settings overridden","value":{"data":{"first_name":"John","phone_number":"+11234567890"},"test":true,"field_overrides":{"last_name":{"required":false,"font_size":9}}}},"submission with signature requests created":{"summary":"submission with signature requests created","value":{"data":{"phone_number":"+11234567890"},"signature_requests":[{"name":"John Smith","email":"john@example.com","fields":["first_name","last_name"],"auth_type":"email_link"}]}},"signature requests for some of the signers":{"summary":"signature requests for some of the signers","value":{"signature_requests":[{"role":"Signer 3","name":"Jane Smith","fields":["last_name"],"auth_type":"email_link"},{"role":"Signer 2","name":"John Smith","fields":["first_name"],"auth_type":"email_link"}]}},"signature requests with a shared field list and an editable prefilled value":{"summary":"signature requests with a shared field list and an editable prefilled value","value":{"data":{"first_name":"John"},"signature_requests":[{"name":"Jane Smith","fields":["last_name","invoice_number"],"ignore_unknown_fields":true,"auth_type":"email_link"},{"name":"John Smith","fields":["first_name"],"prefilled_values_editable":true,"auth_type":"email_link"}]}},"signature requests with empty signatures in data":{"summary":"signature requests with empty signatures in data","value":{"data":{"first_name":"John","last_name":"Smith","signature":{"url":""}},"signature_requests":[{"name":"Jane Smith","fields":["phone_number"],"auth_type":"email_link"}]}}}}},"required":true,"description":"The submission's data and settings."}}},"/submissions/{submission_id}":{"get":{"summary":"Get a submission","tags":["Submissions"],"operationId":"getSubmission","description":"Returns a submission, with its data and links to download its PDF.","parameters":[{"name":"submission_id","in":"path","required":true,"schema":{"type":"string"},"description":"The submission's ID.","example":"sub_1234567890abcdef01"}],"responses":{"200":{"description":"processed submission","content":{"application/json":{"examples":{"processed submission":{"summary":"processed submission","value":{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"processed","test":false,"editable":false,"data":{"first_name":"John","last_name":"Smith","phone_number":"+11234567890"},"data_errors":[],"error_message":null,"metadata":{"user_id":42},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{"pdf":{"state":"processed","error_message":null,"download_url":"https://example.com/submissions/submission.pdf","permanent_url":"https://app.docspring.com/submissions/sub_1234567890abcdef01/files/pdf","filename":"sub_1234567890abcdef01.pdf","content_type":"application/pdf","size":4911,"sha256":"0622971147486e1900037eff229d921d14f5b51aac7171729b2b66f81cdf6585"}},"preview_generated_at":null,"expired":false,"expires_at":"2018-10-27T09:00:00Z","processed_at":"2018-10-20T08:30:05Z","created_at":"2018-10-20T08:30:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Submission"}}}},"404":{"description":"submission not found","content":{"application/json":{"examples":{"submission not found":{"summary":"submission not found","value":{"error":{"code":"not_found","message":"There's no submission with ID sub_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Expire a submission","tags":["Submissions"],"operationId":"expireSubmission","description":"Deletes a submission's data and PDF now, and returns the expired submission.","parameters":[{"name":"submission_id","in":"path","required":true,"schema":{"type":"string"},"description":"The submission's ID.","example":"sub_1234567890abcdef01"}],"responses":{"200":{"description":"submission expired","content":{"application/json":{"examples":{"submission expired":{"summary":"submission expired","value":{"id":"sub_1234567890abcdef01","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"processed","test":false,"editable":false,"data":{},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":true,"expires_at":"2018-10-20T09:00:00Z","processed_at":"2018-10-20T08:30:05Z","created_at":"2018-10-20T08:30:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Submission"}}}},"403":{"description":"test API token","content":{"application/json":{"examples":{"test API token":{"summary":"test API token","value":{"error":{"code":"forbidden","message":"Test API tokens can't delete submissions. Use a live API token.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"submission not found","content":{"application/json":{"examples":{"submission not found":{"summary":"submission not found","value":{"error":{"code":"not_found","message":"There's no submission with ID sub_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/submissions/{submission_id}/generate_preview":{"post":{"summary":"Generate a preview PDF","tags":["Submissions"],"operationId":"generateSubmissionPreview","description":"Generates a preview of a submission's PDF in the background, such as for a submission still waiting for its\nsignature requests. It's in `files.preview` once `preview_generated_at` changes.\n","parameters":[{"name":"submission_id","in":"path","required":true,"schema":{"type":"string"},"description":"The submission's ID.","example":"sub_1234567890abcdef03"}],"responses":{"200":{"description":"preview requested","content":{"application/json":{"examples":{"preview requested":{"summary":"preview requested","value":{"id":"sub_1234567890abcdef03","template_id":"tpl_1234567890abcdef01","template_type":"pdf","template_version":null,"batch_id":null,"source":"api","state":"waiting_for_signature_requests","test":false,"editable":false,"data":{"phone_number":"+11234567890"},"data_errors":[],"error_message":null,"metadata":{},"has_password":false,"signature_requests":[{"id":"srq_1234567890abcdef01","submission_id":"sub_1234567890abcdef03","name":"Test Request User 1","email":"test-request1@example.com","fields":["first_name","last_name"],"metadata":{},"role":"Signer 1","sort_order":0,"state":"pending","data":{},"viewed_at":null,"completed_at":null,"declined_at":null,"auth_type":"email_link","auth_second_factor_type":"none","auth_provider":null,"auth_session_started_at":null,"auth_session_id_hash":null,"auth_user_id_hash":null,"auth_username_hash":null,"auth_phone_number_hash":null,"ip_address":null,"user_agent":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"actions":[],"truncated_text":{},"files":{},"preview_generated_at":null,"expired":false,"expires_at":"2018-10-27T09:00:00Z","processed_at":null,"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Submission"}}}},"409":{"description":"preview not possible","content":{"application/json":{"examples":{"preview not possible":{"summary":"preview not possible","value":{"error":{"code":"conflict","message":"A preview can't be generated: previews are only for submissions with signature requests.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"submission not found","content":{"application/json":{"examples":{"submission not found":{"summary":"submission not found","value":{"error":{"code":"not_found","message":"There's no submission with ID sub_1234567890abcdef09 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/templates":{"get":{"summary":"List templates","tags":["Templates"],"operationId":"listTemplates","description":"Returns the templates in your account (their drafts), newest first, one page at a time. Get a template by its\nID for its HTML, defaults and published versions.\n","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Only list templates whose name contains this text (ignoring case).","example":"rental"},{"name":"parent_folder_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list the templates in this folder (not in its subfolders).","example":"fld_1234567890abcdef01"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50).","example":1},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"templates","content":{"application/json":{"examples":{"templates":{"summary":"templates","value":{"data":[{"id":"tpl_1234567890abcdef02","name":"Invoice","description":null,"template_type":"html","ready":true,"document":null,"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":null,"allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":null,"last_changed_by":null,"created_at":"2018-10-20T08:00:02Z","updated_at":"2018-10-20T09:00:00Z"},{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"templates found by name":{"summary":"templates found by name","value":{"data":[{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"templates in a folder":{"summary":"templates in a folder","value":{"data":[{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/TemplateSummaryList"}}}},"422":{"description":"invalid query parameters","content":{"application/json":{"examples":{"invalid query parameters":{"summary":"invalid query parameters","value":{"error":{"code":"validation_failed","message":"Invalid request: parent_folder_id isn't a folder in this account","details":[{"code":"not_found","message":"isn't a folder in this account","parameter":"parent_folder_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a template","tags":["Templates"],"operationId":"createTemplate","description":"Creates an HTML template, or a PDF template from a PDF you uploaded with the presigned upload (GET\n/uploads/presign): pass its `fields.key` as `cache_id`. To send the PDF with the request instead, use POST\n/templates/upload.\n\nA PDF template is ready to generate PDFs once DocSpring has processed its PDF (`ready` is true). On sync.api\nhosts the request waits for that unless you pass `wait=false`.\n","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been processed before responding. Default true on sync.api hosts."}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"HTML template created","content":{"application/json":{"examples":{"HTML template created":{"summary":"HTML template created","value":{"id":"tpl_1234567890abcdef04","name":"Receipt","description":null,"template_type":"html","ready":true,"document":null,"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":null,"allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":false,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":"<h1>Receipt for {{ name }}</h1>","scss":"h1 { font-size: 24px; }","header_html":null,"footer_html":null,"html_engine_options":{"format":"A4","scale":1,"landscape":true,"print_background":false,"margin_top":"1in","margin_bottom":"1in","margin_left":"1in","margin_right":"1in"},"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[]}},"PDF template created from an upload":{"summary":"PDF template created from an upload","value":{"id":"tpl_1234567890abcdef04","name":"W-8BEN","description":null,"template_type":"pdf","ready":false,"document":{"filename":"fw8ben.pdf","md5":null,"state":"pending","error_message":null,"field_reimport_state":"none","page_count":0,"page_dimensions":null,"has_fillable_fields":null,"page_processing_statuses":[],"field_logic_status":null,"download_url":"https://downloads.docspring.com/cache/original-0000000000?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":null},"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":false,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[]}},"PDF template whose fields DocSpring sets up":{"summary":"PDF template whose fields DocSpring sets up","value":{"id":"tpl_1234567890abcdef04","name":"W-8BEN","description":null,"template_type":"pdf","ready":false,"document":{"filename":"fw8ben.pdf","md5":null,"state":"pending","error_message":null,"field_reimport_state":"none","page_count":0,"page_dimensions":null,"has_fillable_fields":null,"page_processing_statuses":[],"field_logic_status":null,"download_url":"https://downloads.docspring.com/cache/original-0000000000?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":null},"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"english","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":false,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"422":{"description":"invalid template","content":{"application/json":{"examples":{"invalid template":{"summary":"invalid template","value":{"error":{"code":"validation_failed","message":"Invalid request: /html is only for HTML templates; /scss is only for HTML templates","details":[{"code":"not_allowed","message":"is only for HTML templates","pointer":"/html"},{"code":"not_allowed","message":"is only for HTML templates","pointer":"/scss"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"the plan's template limit is reached","content":{"application/json":{"examples":{"the plan's template limit is reached":{"summary":"the plan's template limit is reached","value":{"error":{"code":"upgrade_required","message":"Your Developer plan includes 10 templates. Upgrade to Starter or higher to add more. You can try Starter free for 14 days from the Billing page.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The template's name."},"description":{"type":["string","null"],"description":"Shown under the template's name at the top of its hosted forms, and used as their meta description. Not shown on embedded forms or signature requests."},"template_type":{"title":"TemplateType","type":"string","description":"`pdf`: fields placed on an uploaded PDF. `html`: a PDF rendered from HTML and SCSS. It can't be changed after the template is created.","x-type-description":"The kind of template: `pdf` (fields placed on an uploaded PDF) or `html` (a PDF rendered from HTML).","enum":["pdf","html"]},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder the template is in. Null for a template at the root. Setting it moves the template and all of its published versions."},"locked":{"type":"boolean","description":"A locked template can't be changed or deleted until it's unlocked (`locked` can always be changed)."},"add_signature_request_submission_id_footers":{"type":"boolean","description":"Print the submission ID in the footer of each page of PDFs signed through signature requests."},"ai_field_naming_language":{"title":"AiFieldNamingLanguage","type":"string","description":"The language AI field setup names fields in: `auto` uses the form's language when it's written in the Latin alphabet without accents, and English otherwise; `english` always uses English; `form_language` uses the form's language and script. New templates take it from your account's template settings. Null for HTML templates.","x-type-description":"The language AI field setup names a PDF template's fields in.","enum":["auto","english","form_language"]},"allow_additional_properties":{"type":"boolean","description":"Accept submission data with properties that aren't fields of the template."},"allow_skipping_optional_fields":{"type":"boolean","description":"Visual forms and signature request forms show the Continue button as soon as the required fields are filled in, without visiting each optional field. The `allowSkippingOptionalFields` embed option overrides it."},"default_form_mode":{"title":"TemplateFormMode","type":"string","description":"The hosted form that /templates/{template_id}/form shows when its URL has no `mode` parameter: `web` (the web form), `visual` (the visual form, where fields are filled in on the PDF) or `dual` (both, in tabs). HTML templates have no visual form, so `web` is the only value they accept.","x-type-description":"Which hosted form a template's form link opens.","enum":["web","visual","dual"]},"editable_submissions":{"type":"boolean","description":"Generate PDFs whose text and check fields stay fillable (\"Generate Editable PDFs\"). A submission's `editable` overrides it."},"embed_domains":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":255},"description":"The sites where the template's signature requests, forms and embedded template editor can be loaded: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). When it's empty, live signature requests don't load on any site, and the embedded template editor loads on every site."},"embed_edit_allow_settings":{"type":"boolean","description":"Allow the embedded template editor to change sensitive template settings (webhooks, redirect URL, encryption, public access, expiration and so on)."},"embed_edit_allow_versioning":{"type":"boolean","description":"Allow the embedded template editor to publish, restore, compare and delete published versions."},"embed_edit_allow_document_replacement":{"type":"boolean","description":"Allow the embedded template editor to replace the template's PDF."},"encrypt_pdfs":{"type":"boolean","description":"Encrypt generated PDFs with `encrypt_pdfs_password`."},"encrypt_pdfs_password":{"type":["string","null"],"writeOnly":true,"description":"The password that opens encrypted PDFs. It's never returned; `has_encrypt_pdfs_password` says if it's set."},"expire_submissions":{"type":"boolean","description":"Delete each submission's data and PDF after `expire_after` `expiration_interval`."},"expire_after":{"type":"integer","minimum":1,"maximum":5256000,"description":"How many `expiration_interval`s a submission's data and PDF are kept for, when `expire_submissions` is on. At most 5256000 (10 years in minutes)."},"expiration_interval":{"title":"ExpirationInterval","type":"string","description":"The unit of `expire_after`.","x-type-description":"A unit of time.","enum":["minutes","hours","days"]},"merge_audit_trail_pdf":{"type":"boolean","description":"Add the audit trail to the end of PDFs signed through signature requests."},"parse_dates_using_template_date_format":{"type":"boolean","description":"Date fields also accept NN/NN/YYYY dates (with slashes, dashes or dots), read in the order of the template's default date format: month first for %m/%d/%Y, day first for %d/%m/%Y. When false, date fields only accept YYYY-MM-DD. Applies to PDF templates: an HTML template's date fields only accept YYYY-MM-DD. Date fields that include a time take RFC 3339 date-times either way."},"public_submissions":{"type":"boolean","description":"Allow anyone with a submission's ID to download its PDF."},"public_web_form":{"type":"boolean","description":"Allow anyone to fill in the template's web form."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where the web form sends people after they submit it."},"slack_webhook_url":{"type":["string","null"],"format":"uri","writeOnly":true,"description":"A Slack incoming webhook URL that is notified about the template's submissions. It's never returned; `has_slack_webhook_url` says if it's set."},"defaults":{"type":"object","properties":{"typeface":{"title":"Typeface","type":["string","null"],"description":"The font of text fields.","x-type-description":"One of the template editor's typefaces.","enum":["Inconsolata","Roboto Mono","Ubuntu Mono","Menlo","Courier","Helvetica","Arial","Calibri","Open Sans","Roboto","Lato","Poppins","Public Sans","Questrial","Times New Roman","Dancing Script","Lovtony Script",null]},"font_size":{"type":["integer","null"],"description":"The font size in points, a whole number.","minimum":1},"character_spacing":{"type":["number","null"],"description":"Extra space between characters, in points (0 to 50).","minimum":0,"maximum":50},"color":{"type":["string","null"],"description":"The text color, as 6 hex digits without `#`, such as `444444`.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"background_color":{"type":["string","null"],"description":"The field's background color, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"bold":{"type":"boolean","description":"Print text in bold."},"uppercase":{"type":"boolean","description":"Print text in capital letters."},"alignment":{"title":"TextAlignment","type":"string","description":"How text is aligned in its field. `justify` lines up both edges of every line of multiline text except the last of each paragraph.","x-type-description":"A horizontal text alignment.","enum":["left","center","right","justify"]},"opacity":{"type":"number","minimum":0,"maximum":1,"description":"The opacity of the field's content, from 0 (invisible) to 1."},"date_format":{"type":["string","null"],"description":"How date fields are printed, as a strftime format such as `%m/%d/%Y`."},"date_time_format":{"type":["string","null"],"description":"How date-time fields are printed, as a strftime format such as `%m/%d/%Y %H:%M:%S`."},"check_color":{"type":["string","null"],"description":"The color of check marks, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"check_character":{"title":"CheckCharacter","type":["string","null"],"x-enum-varnames":["CHECK","HEAVY_CHECK","MULTIPLICATION_X","BALLOT_X","HEAVY_BALLOT_X"],"description":"The character that a ticked check box prints.","x-type-description":"A check mark or cross, as the HTML entity of its character: ✓ (`&#10003;`), ✔ (`&#10004;`), ✖ (`&#10006;`), ✗ (`&#10007;`) or ✘ (`&#10008;`).","enum":["&#10003;","&#10004;","&#10006;","&#10007;","&#10008;",null]},"check_background_color":{"type":["string","null"],"description":"The check box's background color, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"required_field_background_color":{"type":["string","null"],"description":"The background color that highlights required fields on visual forms and signature request forms, as 6 hex digits. PDFs don't print it.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"true_text":{"type":["string","null"],"description":"The text a boolean field prints for `true`."},"false_text":{"type":["string","null"],"description":"The text a boolean field prints for `false`."},"shape_fill_color":{"type":["string","null"],"description":"The fill color of shapes, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"shape_border_color":{"type":["string","null"],"description":"The border color of shapes, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"shape_border_width":{"type":"integer","minimum":1,"description":"The border width of shapes, in whole points (at least 1)."}},"title":"TemplateDefaultsInput","description":"The default style of the template's fields. Setting it replaces the whole object.","x-type-description":"The default style of the template's fields. Each field can override it.","additionalProperties":false},"field_dependencies":{"type":"array","description":"The template's conditional logic rules. Setting them replaces all of the rules.","items":{"type":"object","properties":{"action":{"title":"TemplateFieldDependencyAction","type":"string","description":"What the rule does to its targets when its conditions are met.","x-type-description":"What a conditional logic rule does to its target fields.","enum":["require_and_show","show","require"]},"match":{"title":"TemplateFieldDependencyMatch","type":"string","description":"Whether all of the conditions (the default) or any of them must be met.","x-type-description":"Whether all of a rule's conditions or any of them must be met.","enum":["all","any"]},"conditions":{"type":"array","items":{"title":"TemplateFieldDependencyConditionInput","oneOf":[{"$ref":"#/components/schemas/FieldPresenceCondition"},{"$ref":"#/components/schemas/FieldEqualsCondition"},{"$ref":"#/components/schemas/FieldInCondition"},{"$ref":"#/components/schemas/FieldComparisonCondition"},{"$ref":"#/components/schemas/FieldRangeCondition"}],"discriminator":{"propertyName":"operator","mapping":{"present":"#/components/schemas/FieldPresenceCondition","blank":"#/components/schemas/FieldPresenceCondition","equals":"#/components/schemas/FieldEqualsCondition","not_equals":"#/components/schemas/FieldEqualsCondition","in":"#/components/schemas/FieldInCondition","gt":"#/components/schemas/FieldComparisonCondition","gte":"#/components/schemas/FieldComparisonCondition","lt":"#/components/schemas/FieldComparisonCondition","lte":"#/components/schemas/FieldComparisonCondition","range":"#/components/schemas/FieldRangeCondition"}},"x-type-description":"A condition on a field's value."},"description":"The conditions on other fields' values."},"targets":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"The names of the fields the rule shows or makes required."},"group":{"type":"string","description":"Marks a rule made for a field group in the template editor. Its targets outside the group are removed when the template is saved, and the rule is removed once the group has no fields."}},"title":"TemplateFieldDependencyInput","required":["action","conditions","targets"],"x-type-description":"A conditional logic rule: when other fields' values meet its conditions, it shows its target fields, makes them required, or both.","additionalProperties":false}},"html":{"type":["string","null"],"description":"The HTML of an HTML template, as a Liquid template. Null for PDF templates."},"scss":{"type":["string","null"],"description":"The SCSS of an HTML template."},"header_html":{"type":["string","null"],"description":"The HTML printed at the top of each page of an HTML template."},"footer_html":{"type":["string","null"],"description":"The HTML printed at the bottom of each page of an HTML template."},"html_engine_options":{"type":["object","null"],"properties":{"format":{"title":"PageFormat","type":"string","description":"The paper size. `Custom` uses `width` and `height`.","x-type-description":"A paper size, or `Custom`.","enum":["Letter","Legal","Tabloid","Ledger","CR80","A0","A1","A2","A3","A4","A5","A6","Custom"]},"width":{"type":"string","description":"The page width for the `Custom` format, with a unit (`8.5in`, `210mm`)."},"height":{"type":"string","description":"The page height for the `Custom` format, with a unit."},"scale":{"type":"number","exclusiveMinimum":0,"description":"How much to scale the page, such as `0.8`. `1` prints it at its normal size."},"landscape":{"type":"boolean","description":"Print pages in landscape orientation."},"print_background":{"type":"boolean","description":"Print background colors and images."},"margin_top":{"type":"string","description":"The top margin, with a unit, such as `1in` or `20mm`."},"margin_bottom":{"type":"string","description":"The bottom margin, with a unit."},"margin_left":{"type":"string","description":"The left margin, with a unit."},"margin_right":{"type":"string","description":"The right margin, with a unit."}},"title":"HtmlEngineOptionsInput","description":"Null resets the options to their defaults.","x-type-description":"How an HTML template's PDFs are printed.","additionalProperties":false},"cache_id":{"type":"string","minLength":1,"maxLength":255,"description":"A PDF template's document: the `fields.key` of a file you uploaded with the presigned upload (GET /uploads/presign). Required for a PDF template. To upload the PDF with the request, use POST /templates/upload."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The PDF's file name, for a `cache_id` (presigned uploads don't send one)."},"detect_fields":{"type":"boolean","description":"Set up the PDF's fields as DocSpring's \"Automatically detect fields\" upload option does: import or detect the fields, name them with AI, and set up conditional logic. `field_source`, `field_naming` and `field_logic` choose how. Default false. `document.page_processing_statuses` and `document.field_logic_status` show how it's going, and `document.state` becomes `processed` once every page's fields are set up."},"field_source":{"title":"FieldSetupSource","x-type-description":"Where AI field setup takes a PDF's fields from.","type":"string","enum":["auto","pdf_detection","pdf_form_fields"],"description":"With `detect_fields`, where the fields come from. `auto` (the default) imports the form fields of a fillable PDF and detects the fields of a PDF without them; `pdf_detection` detects the fields from the page layout, even on a fillable PDF; `pdf_form_fields` only imports the PDF's form fields."},"field_naming":{"title":"FieldSetupNaming","x-type-description":"How AI field setup names a PDF's fields.","type":"string","enum":["ai","preserve"],"description":"With `detect_fields`, how the fields are named. `ai` (the default) names them and sets their types and settings with AI; `preserve` keeps the names of the PDF's form fields, and AI only names the fields it detected. `preserve` needs `field_source` `auto` or `pdf_form_fields`."},"field_logic":{"title":"FieldSetupLogic","x-type-description":"Whether AI field setup sets up conditional logic and required fields.","type":"string","enum":["ai","none"],"description":"With `detect_fields`, whether AI reads the whole form once the fields are named and sets up conditional logic and required fields (`ai`) or not (`none`). Default: your account's template settings."}},"required":["template_type"],"description":"The template to create.","additionalProperties":false,"title":"CreateTemplateRequest"},"examples":{"HTML template created":{"summary":"HTML template created","value":{"template_type":"html","name":"Receipt","html":"<h1>Receipt for {{ name }}</h1>","scss":"h1 { font-size: 24px; }","html_engine_options":{"format":"A4","landscape":true},"parent_folder_id":"fld_1234567890abcdef01"}},"PDF template created from an upload":{"summary":"PDF template created from an upload","value":{"template_type":"pdf","cache_id":"cache/original-0000000000","editable_submissions":false,"ai_field_naming_language":"auto"}},"PDF template whose fields DocSpring sets up":{"summary":"PDF template whose fields DocSpring sets up","value":{"template_type":"pdf","name":"W-8BEN","cache_id":"cache/original-0000000000","filename":"fw8ben.pdf","ai_field_naming_language":"english","detect_fields":true,"field_source":"pdf_form_fields","field_naming":"preserve","field_logic":"none"}}}}},"required":true,"description":"The template to create."}}},"/templates/upload":{"post":{"summary":"Create a PDF template from an uploaded PDF","tags":["Templates"],"operationId":"uploadTemplate","description":"Creates a PDF template from a PDF sent with the request (`multipart/form-data`). For large files, upload the\nPDF with the presigned upload (GET /uploads/presign) and create the template with POST /templates.\n","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been processed before responding. Default true on sync.api hosts."}],"responses":{"201":{"description":"PDF template created","content":{"application/json":{"examples":{"PDF template created":{"summary":"PDF template created","value":{"id":"tpl_1234567890abcdef04","name":"W-8BEN","description":null,"template_type":"pdf","ready":false,"document":{"filename":"fw8ben.pdf","md5":"ca6fdfed355b9e89f9a94ee54688a231","state":"pending","error_message":null,"field_reimport_state":"none","page_count":0,"page_dimensions":null,"has_fillable_fields":null,"page_processing_statuses":[],"field_logic_status":null,"download_url":"https://downloads.docspring.com/cache/templates/document/0000000000?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":null},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":false,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"422":{"description":"invalid upload","content":{"application/json":{"examples":{"invalid upload":{"summary":"invalid upload","value":{"error":{"code":"validation_failed","message":"Invalid request: /document must be a file","details":[{"code":"type","message":"must be a file","pointer":"/document"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"the plan's template limit is reached","content":{"application/json":{"examples":{"the plan's template limit is reached":{"summary":"the plan's template limit is reached","value":{"error":{"code":"upgrade_required","message":"Your Developer plan includes 10 templates. Upgrade to Starter or higher to add more. You can try Starter free for 14 days from the Billing page.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","description":"The PDF, and the new template's settings.","required":["document"],"properties":{"document":{"type":"string","format":"binary","description":"The PDF."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"The template's name."},"description":{"type":"string","description":"The template's description."},"parent_folder_id":{"type":"string","minLength":1,"description":"The folder to put the template in. Left out, it's created at the root."},"ai_field_naming_language":{"title":"AiFieldNamingLanguage","x-type-description":"The language AI field setup names a PDF template's fields in.","type":"string","enum":["auto","english","form_language"],"description":"The language AI field setup names fields in: `auto` uses the form's language when it's written in the Latin alphabet without accents, and English otherwise; `english` always uses English; `form_language` uses the form's language and script. Default: your account's template settings."},"detect_fields":{"type":"boolean","description":"Set up the PDF's fields as DocSpring's \"Automatically detect fields\" upload option does: import or detect the fields, name them with AI, and set up conditional logic. `field_source`, `field_naming` and `field_logic` choose how. Default false. `document.page_processing_statuses` and `document.field_logic_status` show how it's going, and `document.state` becomes `processed` once every page's fields are set up."},"field_source":{"title":"FieldSetupSource","x-type-description":"Where AI field setup takes a PDF's fields from.","type":"string","enum":["auto","pdf_detection","pdf_form_fields"],"description":"With `detect_fields`, where the fields come from. `auto` (the default) imports the form fields of a fillable PDF and detects the fields of a PDF without them; `pdf_detection` detects the fields from the page layout, even on a fillable PDF; `pdf_form_fields` only imports the PDF's form fields."},"field_naming":{"title":"FieldSetupNaming","x-type-description":"How AI field setup names a PDF's fields.","type":"string","enum":["ai","preserve"],"description":"With `detect_fields`, how the fields are named. `ai` (the default) names them and sets their types and settings with AI; `preserve` keeps the names of the PDF's form fields, and AI only names the fields it detected. `preserve` needs `field_source` `auto` or `pdf_form_fields`."},"field_logic":{"title":"FieldSetupLogic","x-type-description":"Whether AI field setup sets up conditional logic and required fields.","type":"string","enum":["ai","none"],"description":"With `detect_fields`, whether AI reads the whole form once the fields are named and sets up conditional logic and required fields (`ai`) or not (`none`). Default: your account's template settings."}},"additionalProperties":false,"title":"UploadTemplateRequest"}}},"required":true,"description":"The PDF, and the new template's settings."}}},"/templates/{template_id}":{"get":{"summary":"Get a template","tags":["Templates"],"operationId":"getTemplate","description":"Returns a template: its draft, or one of its published versions.","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"description":"A published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `draft`.","example":"latest"}],"responses":{"200":{"description":"PDF template","content":{"application/json":{"examples":{"PDF template":{"summary":"PDF template","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[]}},"HTML template":{"summary":"HTML template","value":{"id":"tpl_1234567890abcdef02","name":"Invoice","description":null,"template_type":"html","ready":true,"document":null,"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":null,"allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":null,"last_changed_by":null,"created_at":"2018-10-20T08:00:02Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":"<h1>Invoice {{ invoice_number }}</h1>","scss":"h1 { color: #444; }","header_html":null,"footer_html":null,"html_engine_options":{"format":"A4","scale":1,"landscape":false,"print_background":false,"margin_top":"1in","margin_bottom":"1in","margin_left":"1in","margin_right":"1in"},"embed_edit_token":"exampleEmbedEditTokenForTemplate2","versions":[]}},"published version":{"summary":"published version","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/0.1.0/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef&version=0.1.0"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":"0.1.0","latest_version":"0.1.0","version_published_at":"2018-10-20T09:00:00Z","locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[{"version":"0.1.0","description":"First version","published_at":"2018-10-20T09:00:00Z","published_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null}}]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid version","content":{"application/json":{"examples":{"invalid version":{"summary":"invalid version","value":{"error":{"code":"validation_failed","message":"Invalid request: version must be a version like 1.2.3 or 1, or latest or draft","details":[{"code":"pattern","message":"must be a version like 1.2.3 or 1, or latest or draft","parameter":"version"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a template","tags":["Templates"],"operationId":"updateTemplate","description":"Changes a template's draft. Properties left out keep their values. `defaults` and `html_engine_options`\nreplace the whole object. Setting `parent_folder_id` moves the template and all of its published versions.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"200":{"description":"template updated","content":{"application/json":{"examples":{"template updated":{"summary":"template updated","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract 2025","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"form_language","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"dual","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":true,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":10,"bold":true},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"409":{"description":"template is locked","content":{"application/json":{"examples":{"template is locked":{"summary":"template is locked","value":{"error":{"code":"conflict","message":"Template tpl_1234567890abcdef01 is locked, so it can't be changed. Set locked to false first, in a request of its own.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid update","content":{"application/json":{"examples":{"invalid update":{"summary":"invalid update","value":{"error":{"code":"validation_failed","message":"Invalid request: /header_html is only for HTML templates","details":[{"code":"not_allowed","message":"is only for HTML templates","pointer":"/header_html"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The template's name."},"description":{"type":["string","null"],"description":"Shown under the template's name at the top of its hosted forms, and used as their meta description. Not shown on embedded forms or signature requests."},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The ID of the folder the template is in. Null for a template at the root. Setting it moves the template and all of its published versions."},"locked":{"type":"boolean","description":"A locked template can't be changed or deleted until it's unlocked (`locked` can always be changed)."},"add_signature_request_submission_id_footers":{"type":"boolean","description":"Print the submission ID in the footer of each page of PDFs signed through signature requests."},"ai_field_naming_language":{"title":"AiFieldNamingLanguage","type":"string","description":"The language AI field setup names fields in: `auto` uses the form's language when it's written in the Latin alphabet without accents, and English otherwise; `english` always uses English; `form_language` uses the form's language and script. New templates take it from your account's template settings. Null for HTML templates.","x-type-description":"The language AI field setup names a PDF template's fields in.","enum":["auto","english","form_language"]},"allow_additional_properties":{"type":"boolean","description":"Accept submission data with properties that aren't fields of the template."},"allow_skipping_optional_fields":{"type":"boolean","description":"Visual forms and signature request forms show the Continue button as soon as the required fields are filled in, without visiting each optional field. The `allowSkippingOptionalFields` embed option overrides it."},"default_form_mode":{"title":"TemplateFormMode","type":"string","description":"The hosted form that /templates/{template_id}/form shows when its URL has no `mode` parameter: `web` (the web form), `visual` (the visual form, where fields are filled in on the PDF) or `dual` (both, in tabs). HTML templates have no visual form, so `web` is the only value they accept.","x-type-description":"Which hosted form a template's form link opens.","enum":["web","visual","dual"]},"editable_submissions":{"type":"boolean","description":"Generate PDFs whose text and check fields stay fillable (\"Generate Editable PDFs\"). A submission's `editable` overrides it."},"embed_domains":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":255},"description":"The sites where the template's signature requests, forms and embedded template editor can be loaded: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). When it's empty, live signature requests don't load on any site, and the embedded template editor loads on every site."},"embed_edit_allow_settings":{"type":"boolean","description":"Allow the embedded template editor to change sensitive template settings (webhooks, redirect URL, encryption, public access, expiration and so on)."},"embed_edit_allow_versioning":{"type":"boolean","description":"Allow the embedded template editor to publish, restore, compare and delete published versions."},"embed_edit_allow_document_replacement":{"type":"boolean","description":"Allow the embedded template editor to replace the template's PDF."},"encrypt_pdfs":{"type":"boolean","description":"Encrypt generated PDFs with `encrypt_pdfs_password`."},"encrypt_pdfs_password":{"type":["string","null"],"writeOnly":true,"description":"The password that opens encrypted PDFs. It's never returned; `has_encrypt_pdfs_password` says if it's set."},"expire_submissions":{"type":"boolean","description":"Delete each submission's data and PDF after `expire_after` `expiration_interval`."},"expire_after":{"type":"integer","minimum":1,"maximum":5256000,"description":"How many `expiration_interval`s a submission's data and PDF are kept for, when `expire_submissions` is on. At most 5256000 (10 years in minutes)."},"expiration_interval":{"title":"ExpirationInterval","type":"string","description":"The unit of `expire_after`.","x-type-description":"A unit of time.","enum":["minutes","hours","days"]},"merge_audit_trail_pdf":{"type":"boolean","description":"Add the audit trail to the end of PDFs signed through signature requests."},"parse_dates_using_template_date_format":{"type":"boolean","description":"Date fields also accept NN/NN/YYYY dates (with slashes, dashes or dots), read in the order of the template's default date format: month first for %m/%d/%Y, day first for %d/%m/%Y. When false, date fields only accept YYYY-MM-DD. Applies to PDF templates: an HTML template's date fields only accept YYYY-MM-DD. Date fields that include a time take RFC 3339 date-times either way."},"public_submissions":{"type":"boolean","description":"Allow anyone with a submission's ID to download its PDF."},"public_web_form":{"type":"boolean","description":"Allow anyone to fill in the template's web form."},"redirect_url":{"type":["string","null"],"format":"uri","description":"Where the web form sends people after they submit it."},"slack_webhook_url":{"type":["string","null"],"format":"uri","writeOnly":true,"description":"A Slack incoming webhook URL that is notified about the template's submissions. It's never returned; `has_slack_webhook_url` says if it's set."},"defaults":{"type":"object","properties":{"typeface":{"title":"Typeface","type":["string","null"],"description":"The font of text fields.","x-type-description":"One of the template editor's typefaces.","enum":["Inconsolata","Roboto Mono","Ubuntu Mono","Menlo","Courier","Helvetica","Arial","Calibri","Open Sans","Roboto","Lato","Poppins","Public Sans","Questrial","Times New Roman","Dancing Script","Lovtony Script",null]},"font_size":{"type":["integer","null"],"description":"The font size in points, a whole number.","minimum":1},"character_spacing":{"type":["number","null"],"description":"Extra space between characters, in points (0 to 50).","minimum":0,"maximum":50},"color":{"type":["string","null"],"description":"The text color, as 6 hex digits without `#`, such as `444444`.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"background_color":{"type":["string","null"],"description":"The field's background color, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"bold":{"type":"boolean","description":"Print text in bold."},"uppercase":{"type":"boolean","description":"Print text in capital letters."},"alignment":{"title":"TextAlignment","type":"string","description":"How text is aligned in its field. `justify` lines up both edges of every line of multiline text except the last of each paragraph.","x-type-description":"A horizontal text alignment.","enum":["left","center","right","justify"]},"opacity":{"type":"number","minimum":0,"maximum":1,"description":"The opacity of the field's content, from 0 (invisible) to 1."},"date_format":{"type":["string","null"],"description":"How date fields are printed, as a strftime format such as `%m/%d/%Y`."},"date_time_format":{"type":["string","null"],"description":"How date-time fields are printed, as a strftime format such as `%m/%d/%Y %H:%M:%S`."},"check_color":{"type":["string","null"],"description":"The color of check marks, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"check_character":{"title":"CheckCharacter","type":["string","null"],"x-enum-varnames":["CHECK","HEAVY_CHECK","MULTIPLICATION_X","BALLOT_X","HEAVY_BALLOT_X"],"description":"The character that a ticked check box prints.","x-type-description":"A check mark or cross, as the HTML entity of its character: ✓ (`&#10003;`), ✔ (`&#10004;`), ✖ (`&#10006;`), ✗ (`&#10007;`) or ✘ (`&#10008;`).","enum":["&#10003;","&#10004;","&#10006;","&#10007;","&#10008;",null]},"check_background_color":{"type":["string","null"],"description":"The check box's background color, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"required_field_background_color":{"type":["string","null"],"description":"The background color that highlights required fields on visual forms and signature request forms, as 6 hex digits. PDFs don't print it.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"true_text":{"type":["string","null"],"description":"The text a boolean field prints for `true`."},"false_text":{"type":["string","null"],"description":"The text a boolean field prints for `false`."},"shape_fill_color":{"type":["string","null"],"description":"The fill color of shapes, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"shape_border_color":{"type":["string","null"],"description":"The border color of shapes, as 6 hex digits.","pattern":"^[A-Fa-f0-9]{6}$","x-pattern-message":"must be a 6-digit hex color without #, like FF0000"},"shape_border_width":{"type":"integer","minimum":1,"description":"The border width of shapes, in whole points (at least 1)."}},"title":"TemplateDefaultsInput","description":"The default style of the template's fields. Setting it replaces the whole object.","x-type-description":"The default style of the template's fields. Each field can override it.","additionalProperties":false},"field_dependencies":{"type":"array","description":"The template's conditional logic rules. Setting them replaces all of the rules.","items":{"type":"object","properties":{"action":{"title":"TemplateFieldDependencyAction","type":"string","description":"What the rule does to its targets when its conditions are met.","x-type-description":"What a conditional logic rule does to its target fields.","enum":["require_and_show","show","require"]},"match":{"title":"TemplateFieldDependencyMatch","type":"string","description":"Whether all of the conditions (the default) or any of them must be met.","x-type-description":"Whether all of a rule's conditions or any of them must be met.","enum":["all","any"]},"conditions":{"type":"array","items":{"title":"TemplateFieldDependencyConditionInput","oneOf":[{"$ref":"#/components/schemas/FieldPresenceCondition"},{"$ref":"#/components/schemas/FieldEqualsCondition"},{"$ref":"#/components/schemas/FieldInCondition"},{"$ref":"#/components/schemas/FieldComparisonCondition"},{"$ref":"#/components/schemas/FieldRangeCondition"}],"discriminator":{"propertyName":"operator","mapping":{"present":"#/components/schemas/FieldPresenceCondition","blank":"#/components/schemas/FieldPresenceCondition","equals":"#/components/schemas/FieldEqualsCondition","not_equals":"#/components/schemas/FieldEqualsCondition","in":"#/components/schemas/FieldInCondition","gt":"#/components/schemas/FieldComparisonCondition","gte":"#/components/schemas/FieldComparisonCondition","lt":"#/components/schemas/FieldComparisonCondition","lte":"#/components/schemas/FieldComparisonCondition","range":"#/components/schemas/FieldRangeCondition"}},"x-type-description":"A condition on a field's value."},"description":"The conditions on other fields' values."},"targets":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"The names of the fields the rule shows or makes required."},"group":{"type":"string","description":"Marks a rule made for a field group in the template editor. Its targets outside the group are removed when the template is saved, and the rule is removed once the group has no fields."}},"title":"TemplateFieldDependencyInput","required":["action","conditions","targets"],"x-type-description":"A conditional logic rule: when other fields' values meet its conditions, it shows its target fields, makes them required, or both.","additionalProperties":false}},"html":{"type":["string","null"],"description":"The HTML of an HTML template, as a Liquid template. Null for PDF templates."},"scss":{"type":["string","null"],"description":"The SCSS of an HTML template."},"header_html":{"type":["string","null"],"description":"The HTML printed at the top of each page of an HTML template."},"footer_html":{"type":["string","null"],"description":"The HTML printed at the bottom of each page of an HTML template."},"html_engine_options":{"type":["object","null"],"properties":{"format":{"title":"PageFormat","type":"string","description":"The paper size. `Custom` uses `width` and `height`.","x-type-description":"A paper size, or `Custom`.","enum":["Letter","Legal","Tabloid","Ledger","CR80","A0","A1","A2","A3","A4","A5","A6","Custom"]},"width":{"type":"string","description":"The page width for the `Custom` format, with a unit (`8.5in`, `210mm`)."},"height":{"type":"string","description":"The page height for the `Custom` format, with a unit."},"scale":{"type":"number","exclusiveMinimum":0,"description":"How much to scale the page, such as `0.8`. `1` prints it at its normal size."},"landscape":{"type":"boolean","description":"Print pages in landscape orientation."},"print_background":{"type":"boolean","description":"Print background colors and images."},"margin_top":{"type":"string","description":"The top margin, with a unit, such as `1in` or `20mm`."},"margin_bottom":{"type":"string","description":"The bottom margin, with a unit."},"margin_left":{"type":"string","description":"The left margin, with a unit."},"margin_right":{"type":"string","description":"The right margin, with a unit."}},"title":"HtmlEngineOptionsInput","description":"Null resets the options to their defaults.","x-type-description":"How an HTML template's PDFs are printed.","additionalProperties":false}},"description":"The settings to change. Properties left out keep their values.","additionalProperties":false,"title":"UpdateTemplateRequest"},"examples":{"template updated":{"summary":"template updated","value":{"name":"Rental Contract 2025","parent_folder_id":null,"slack_webhook_url":"https://hooks.slack.com/services/T000/B000/XXXX","encrypt_pdfs_password":null,"default_form_mode":"dual","ai_field_naming_language":"form_language","defaults":{"typeface":"Helvetica","font_size":10,"bold":true}}},"signature request footers turned on":{"summary":"signature request footers turned on","value":{"add_signature_request_submission_id_footers":true}},"embed domains set":{"summary":"embed domains set","value":{"embed_domains":["app.example.com","*.example.org","https://localhost:3000"]}},"embed domains cleared":{"summary":"embed domains cleared","value":{"embed_domains":[]}},"conditional logic updated":{"summary":"conditional logic updated","value":{"field_dependencies":[{"action":"show","match":"all","conditions":[{"field":"first_name","operator":"equals","value":"John"}],"targets":["last_name"]}]}},"conditional logic on a number field":{"summary":"conditional logic on a number field","value":{"field_dependencies":[{"action":"require","match":"any","conditions":[{"field":"phone_number","operator":"range","value":1,"range_max":"10"},{"field":"phone_number","operator":"gt","value":"99.5"}],"targets":["last_name"]}]}},"conditional logic sent back as a template returned it":{"summary":"conditional logic sent back as a template returned it","value":{"field_dependencies":[{"action":"show","match":"all","conditions":[{"field":"first_name","operator":"present"},{"field":"last_name","operator":"in","value":["Smith"]},{"field":"last_name","operator":"in","value":["Jones"]}],"targets":["phone_number"]}]}}}}},"required":true,"description":"The settings to change. Properties left out keep their values."}},"delete":{"summary":"Delete a template","tags":["Templates"],"operationId":"deleteTemplate","description":"Deletes a template's draft and all of its published versions, or one published version (`version`). Returns\nthe template as it was before it was deleted.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef02"},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^(\\d+\\.\\d+\\.\\d+|draft)$","x-pattern-message":"must be a full version like 1.2.3, or draft"},"description":"Delete only this published version (`1.2.0`) or the draft (`draft`, when no version has been published). Without it, the draft and every published version are deleted."}],"responses":{"200":{"description":"template deleted","content":{"application/json":{"examples":{"template deleted":{"summary":"template deleted","value":{"id":"tpl_1234567890abcdef02","name":"Invoice","description":null,"template_type":"html","ready":true,"document":null,"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":null,"allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":false,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":null,"last_changed_by":null,"created_at":"2018-10-20T08:00:02Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":"<h1>Invoice {{ invoice_number }}</h1>","scss":"h1 { color: #444; }","header_html":null,"footer_html":null,"html_engine_options":{"format":"A4","scale":1,"landscape":false,"print_background":false,"margin_top":"1in","margin_bottom":"1in","margin_left":"1in","margin_right":"1in"},"embed_edit_token":"exampleEmbedEditTokenForTemplate2","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"409":{"description":"template is locked","content":{"application/json":{"examples":{"template is locked":{"summary":"template is locked","value":{"error":{"code":"conflict","message":"Template tpl_1234567890abcdef01 is locked, so it can't be deleted. Set locked to false first (PUT /templates/tpl_1234567890abcdef01).","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid version","content":{"application/json":{"examples":{"invalid version":{"summary":"invalid version","value":{"error":{"code":"validation_failed","message":"Invalid request: version must be a full version like 1.2.3, or draft","details":[{"code":"pattern","message":"must be a full version like 1.2.3, or draft","parameter":"version"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/templates/{template_id}/document":{"put":{"summary":"Replace a template's PDF","tags":["Templates"],"operationId":"updateTemplateDocument","description":"Replaces a PDF template's PDF with one you uploaded with the presigned upload (GET /uploads/presign). The\nfields stay where they are, unless `reimport_fields` replaces them with the new PDF's fillable fields. To send\nthe PDF with the request instead, use PUT /templates/{template_id}/document/upload.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been processed before responding. Default true on sync.api hosts."}],"x-codegen-request-body-name":"body","responses":{"200":{"description":"PDF replaced","content":{"application/json":{"examples":{"PDF replaced":{"summary":"PDF replaced","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":false,"document":{"filename":"fw8ben.pdf","md5":null,"state":"pending","error_message":null,"field_reimport_state":"none","page_count":0,"page_dimensions":null,"has_fillable_fields":null,"page_processing_statuses":[],"field_logic_status":null,"download_url":"https://downloads.docspring.com/cache/original-0000000000?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":null},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"409":{"description":"template is locked, so its fields can't be re-imported","content":{"application/json":{"examples":{"template is locked, so its fields can't be re-imported":{"summary":"template is locked, so its fields can't be re-imported","value":{"error":{"code":"conflict","message":"Template tpl_1234567890abcdef01 is locked, so it can't be changed. Set locked to false first, in a request of its own.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"not a PDF template","content":{"application/json":{"examples":{"not a PDF template":{"summary":"not a PDF template","value":{"error":{"code":"validation_failed","message":"Invalid request: /cache_id is only for PDF templates","details":[{"code":"not_allowed","message":"is only for PDF templates","pointer":"/cache_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The new PDF.","required":["cache_id"],"properties":{"cache_id":{"type":"string","minLength":1,"maxLength":255,"description":"The `fields.key` of the new PDF, uploaded with the presigned upload (GET /uploads/presign)."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The PDF's file name, for a `cache_id` (presigned uploads don't send one)."},"reimport_fields":{"type":"boolean","description":"Replace all of the template's fields with the fillable fields in the new PDF, once DocSpring has processed it (`document.field_reimport_state`). As on a first upload, the default typeface, font size, bold and color are taken from the PDF's fields; the template's other settings are kept. If the PDF has no fillable fields, the template keeps its fields. A locked template can't re-import its fields."}},"additionalProperties":false,"title":"UpdateTemplateDocumentRequest"},"examples":{"PDF replaced":{"summary":"PDF replaced","value":{"cache_id":"cache/original-0000000000","filename":"fw8ben.pdf","reimport_fields":true}}}}},"required":true,"description":"The new PDF."}}},"/templates/{template_id}/document/upload":{"put":{"summary":"Replace a template's PDF with an uploaded PDF","tags":["Templates"],"operationId":"uploadTemplateDocument","description":"Replaces a PDF template's PDF with one sent with the request (`multipart/form-data`). The fields stay where\nthey are, unless `reimport_fields` replaces them with the new PDF's fillable fields.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"},"description":"Wait until the PDF has been processed before responding. Default true on sync.api hosts."}],"responses":{"200":{"description":"PDF replaced","content":{"application/json":{"examples":{"PDF replaced":{"summary":"PDF replaced","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":false,"document":{"filename":"fw8ben.pdf","md5":"ca6fdfed355b9e89f9a94ee54688a231","state":"pending","error_message":null,"field_reimport_state":"none","page_count":0,"page_dimensions":null,"has_fillable_fields":null,"page_processing_statuses":[],"field_logic_status":null,"download_url":"https://downloads.docspring.com/cache/templates/document/0000000000?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":null},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"422":{"description":"not a PDF template","content":{"application/json":{"examples":{"not a PDF template":{"summary":"not a PDF template","value":{"error":{"code":"validation_failed","message":"Invalid request: /document is only for PDF templates","details":[{"code":"not_allowed","message":"is only for PDF templates","pointer":"/document"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","description":"The new PDF.","required":["document"],"properties":{"document":{"type":"string","format":"binary","description":"The new PDF."},"reimport_fields":{"type":"boolean","description":"Replace all of the template's fields with the fillable fields in the new PDF, once DocSpring has processed it (`document.field_reimport_state`). As on a first upload, the default typeface, font size, bold and color are taken from the PDF's fields; the template's other settings are kept. If the PDF has no fillable fields, the template keeps its fields. A locked template can't re-import its fields."}},"additionalProperties":false,"title":"UploadTemplateDocumentRequest"}}},"required":true,"description":"The new PDF."}}},"/templates/{template_id}/copy":{"post":{"summary":"Copy a template","tags":["Templates"],"operationId":"copyTemplate","description":"Copies a template (its draft, or a published version) into a new template.","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"template copied","content":{"application/json":{"examples":{"template copied":{"summary":"template copied","value":{"id":"tpl_1234567890abcdef04","name":"Rental Contract (2)","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef04/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef04/original_pdf?token=exampleDocumentDownloadToken0001"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenGenerated001","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"422":{"description":"invalid copy","content":{"application/json":{"examples":{"invalid copy":{"summary":"invalid copy","value":{"error":{"code":"validation_failed","message":"Invalid request: /name can't be empty","details":[{"code":"minLength","message":"can't be empty","pointer":"/name"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"the plan's template limit is reached","content":{"application/json":{"examples":{"the plan's template limit is reached":{"summary":"the plan's template limit is reached","value":{"error":{"code":"upgrade_required","message":"Your Developer plan includes 10 templates. Upgrade to Starter or higher to add more. You can try Starter free for 14 days from the Billing page.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Settings for the copy.","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Default: the template's name followed by a number, such as \"Contract (2)\". For a published version, the name followed by the version, such as \"Contract (v1.2.0)\"."},"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The folder to put the copy in. Null puts it at the root. Left out, the copy goes in the template's own folder."},"version":{"type":"string","pattern":"^\\d+(\\.\\d+(\\.\\d+)?)?$","description":"Copy this published version (`1.2.0`, or `1` for the latest 1.x.x) instead of the draft.","x-pattern-message":"must be a published version like 1.2.3 or 1"}},"additionalProperties":false,"title":"CopyTemplateRequest"},"examples":{"template copied":{"summary":"template copied","value":{"parent_folder_id":"fld_1234567890abcdef01"}},"template copied into the template's own folder":{"summary":"template copied into the template's own folder","value":{}},"template copied to the root":{"summary":"template copied to the root","value":{"parent_folder_id":null}}}}},"description":"Settings for the copy."}}},"/templates/{template_id}/move":{"post":{"summary":"Move a template to a folder","tags":["Templates"],"operationId":"moveTemplate","description":"Moves a template and all of its published versions to a folder, or to the root (`null`).","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"200":{"description":"template moved","content":{"application/json":{"examples":{"template moved":{"summary":"template moved","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":null,"path":"/","version":null,"latest_version":null,"version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T08:30:00Z","last_changed_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null},"created_at":"2018-10-20T08:00:01Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"422":{"description":"invalid move","content":{"application/json":{"examples":{"invalid move":{"summary":"invalid move","value":{"error":{"code":"validation_failed","message":"Invalid request: /parent_folder isn't a documented property. Did you mean 'parent_folder_id'?; /parent_folder_id is required","details":[{"code":"unknown_property","message":"isn't a documented property. Did you mean 'parent_folder_id'?","pointer":"/parent_folder"},{"code":"required","message":"is required","pointer":"/parent_folder_id"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Where to move the template.","required":["parent_folder_id"],"properties":{"parent_folder_id":{"type":["string","null"],"minLength":1,"description":"The folder to move the template and all of its published versions to. Null moves them to the root."}},"additionalProperties":false,"title":"MoveTemplateRequest"},"examples":{"template moved":{"summary":"template moved","value":{"parent_folder_id":null}}}}},"required":true,"description":"Where to move the template."}}},"/templates/{template_id}/publish_version":{"post":{"summary":"Publish a template version","tags":["Templates"],"operationId":"publishTemplateVersion","description":"Publishes the template's draft as a new version that doesn't change. `version_type` says which part of the\nlatest version number goes up.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"201":{"description":"version published","content":{"application/json":{"examples":{"version published":{"summary":"version published","value":{"version":"0.1.0","description":"Added the signature fields","published_at":"2018-10-20T09:00:00Z","published_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null}}}},"schema":{"$ref":"#/components/schemas/TemplateVersion"}}}},"422":{"description":"invalid version type","content":{"application/json":{"examples":{"invalid version type":{"summary":"invalid version type","value":{"error":{"code":"validation_failed","message":"Invalid request: /version_type must be one of: \"major\", \"minor\", \"patch\"","details":[{"code":"enum","message":"must be one of: \"major\", \"minor\", \"patch\"","pointer":"/version_type"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"published at the same time","content":{"application/json":{"examples":{"published at the same time":{"summary":"published at the same time","value":{"error":{"code":"conflict","message":"Another request published a version of template tpl_1234567890abcdef01 at the same time. Publish again to create the next version.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The version to publish.","required":["version_type"],"properties":{"version_type":{"title":"TemplateVersionType","x-type-description":"Which part of a version number to increase.","type":"string","enum":["major","minor","patch"],"description":"Which part of the latest version number to increase."},"description":{"type":"string","maxLength":500,"description":"What changed in the version, shown with it in DocSpring."}},"additionalProperties":false,"title":"PublishTemplateVersionRequest"},"examples":{"version published":{"summary":"version published","value":{"version_type":"minor","description":"Added the signature fields"}}}}},"required":true,"description":"The version to publish."}}},"/templates/{template_id}/restore_version":{"post":{"summary":"Restore a template version","tags":["Templates"],"operationId":"restoreTemplateVersion","description":"Replaces the template's draft with a copy of one of its published versions.","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"}],"x-codegen-request-body-name":"body","responses":{"200":{"description":"version restored","content":{"application/json":{"examples":{"version restored":{"summary":"version restored","value":{"id":"tpl_1234567890abcdef01","name":"Rental Contract","description":null,"template_type":"pdf","ready":true,"document":{"filename":"blank_pdf.pdf","md5":"1c32d785398e3a7eaab0e9b876903cc6","state":"processed","error_message":null,"field_reimport_state":"none","page_count":1,"page_dimensions":[[612,792]],"has_fillable_fields":false,"page_processing_statuses":[{"image":"processed","fields":"disabled","ai_naming":null,"ai_error":null,"detected_boxes":null}],"field_logic_status":null,"download_url":"https://downloads.docspring.com/store/acc_1234567890abcdef01/templates/tpl_1234567890abcdef01/draft/document/original-0000000000.abcdef1234567890abcd.pdf?Expires=1609491600&Signature=MEUCIQDexampleSignatureOnlyForTheDocs~exampleexampleexample_&Key-Pair-Id=K2EXAMPLEKEYID&Hash-Algorithm=SHA256","permanent_url":"https://app.docspring.com/templates/tpl_1234567890abcdef01/original_pdf?token=123456789abcdef"},"parent_folder_id":"fld_1234567890abcdef01","path":"/Contracts","version":null,"latest_version":"0.1.0","version_published_at":null,"locked":false,"add_signature_request_submission_id_footers":true,"ai_field_naming_language":"auto","allow_additional_properties":false,"allow_skipping_optional_fields":false,"default_form_mode":"web","editable_submissions":false,"embed_domains":[],"embed_edit_allow_settings":false,"embed_edit_allow_versioning":false,"embed_edit_allow_document_replacement":false,"encrypt_pdfs":false,"has_encrypt_pdfs_password":true,"expire_submissions":true,"expire_after":7,"expiration_interval":"days","merge_audit_trail_pdf":true,"parse_dates_using_template_date_format":false,"public_submissions":false,"public_web_form":false,"redirect_url":null,"has_slack_webhook_url":false,"last_changed_at":"2018-10-20T09:00:00Z","last_changed_by":{"type":"api","user_id":null,"external_id":null,"name":null,"email":null},"created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z","defaults":{"typeface":"Helvetica","font_size":11,"character_spacing":0,"color":"444444","opacity":1,"date_format":"%m/%d/%Y","date_time_format":"%m/%d/%Y %H:%M:%S","check_color":"444444","shape_border_color":"4A90E2"},"field_dependencies":[],"html":null,"scss":null,"header_html":null,"footer_html":null,"html_engine_options":null,"embed_edit_token":"exampleEmbedEditTokenForTemplate1","versions":[{"version":"0.1.0","description":null,"published_at":"2018-10-20T09:00:00Z","published_by":{"type":"user","user_id":"usr_1234567890abcdef01","external_id":null,"name":"Test User 1","email":null}}]}}},"schema":{"$ref":"#/components/schemas/Template"}}}},"409":{"description":"template is locked","content":{"application/json":{"examples":{"template is locked":{"summary":"template is locked","value":{"error":{"code":"conflict","message":"Template tpl_1234567890abcdef01 is locked, so a version can't be restored into it. Set locked to false first (PUT /templates/tpl_1234567890abcdef01).","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"unknown version","content":{"application/json":{"examples":{"unknown version":{"summary":"unknown version","value":{"error":{"code":"validation_failed","message":"Invalid request: /version isn't a published version of this template","details":[{"code":"not_found","message":"isn't a published version of this template","pointer":"/version"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The version to restore.","required":["version"],"properties":{"version":{"type":"string","pattern":"^\\d+(\\.\\d+(\\.\\d+)?)?$","description":"The published version to restore to the draft (`1.2.0`, or `1` for the latest 1.x.x).","x-pattern-message":"must be a published version like 1.2.3 or 1"}},"additionalProperties":false,"title":"RestoreTemplateVersionRequest"},"examples":{"version restored":{"summary":"version restored","value":{"version":"0.1.0"}}}}},"required":true,"description":"The version to restore."}}},"/templates/{template_id}/schema":{"get":{"summary":"Get the JSON Schema of a template's submission data","tags":["Templates"],"operationId":"getTemplateSchema","description":"Returns the JSON Schema that a submission's `data` must match. Use it to check data before you create\nsubmissions, or to build a form for the template's fields.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"description":"The template version: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published), the version a submission uses by default.","example":"draft"}],"responses":{"200":{"description":"template schema","content":{"application/json":{"examples":{"template schema":{"summary":"template schema","value":{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://api.docspring.com/api/v2/templates/tpl_1234567890abcdef01/schema","title":"Rental Contract","description":"JSON Schema generated by DocSpring.com","definitions":{},"type":"object","properties":{"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"phone_number":{"type":["string","null"],"title":"Phone Number"}},"required":["first_name","last_name"],"additionalProperties":false}}},"schema":{"$ref":"#/components/schemas/TemplateDataSchema"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/templates/{template_id}/model_code":{"get":{"summary":"Generate typed code for a template's submission data","tags":["Templates"],"operationId":"getTemplateModelCode","description":"Generates types for a template's submission data in TypeScript, JavaScript, Ruby, Python, PHP, Java, C#,\nElixir or Go, so your app catches mistakes before it calls the API. `root_type_name` is the type of the whole\n`data` object. Java returns every class in `code`, each under a `// ClassName.java` comment. A template with\nno named fields returns 422.\n","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template's ID.","example":"tpl_1234567890abcdef01"},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$","x-pattern-message":"must be a version like 1.2.3 or 1, or latest or draft"},"description":"The template version: a published version (`1.2.0`, or `1` for the latest 1.x.x), `latest` or `draft`. Default `latest` (the draft when no version has been published), the version a submission uses by default.","example":"draft"},{"name":"lang","in":"query","required":true,"schema":{"title":"ModelCodeLanguage","x-type-description":"A language that DocSpring generates typed code in.","type":"string","enum":["typescript","javascript","ruby","python","php","java","csharp","elixir","go"]},"description":"The language to generate the code in.","example":"typescript"}],"responses":{"200":{"description":"model code","content":{"application/json":{"examples":{"model code":{"summary":"model code","value":{"lang":"typescript","root_type_name":"RentalContract","code":"// To parse this data:\n//\n//   import { Convert, RentalContract } from \"./rental-contract\";\n//\n//   const rentalContract = Convert.toRentalContract(json);\n//\n// These functions will throw an error if the JSON doesn't\n// match the expected interface, even if the JSON is valid.\n\n/**\n * JSON Schema generated by DocSpring.com\n */\nexport interface RentalContract {\n    first_name:    string;\n    last_name:     string;\n    phone_number?: null | string;\n}\n\n// Converts JSON strings to/from your types\n// and asserts the results of JSON.parse at runtime\nexport class Convert {\n    public static toRentalContract(json: string): RentalContract {\n        return cast(JSON.parse(json), r(\"RentalContract\"));\n    }\n\n    public static rentalContractToJson(value: RentalContract): string {\n        return JSON.stringify(uncast(value, r(\"RentalContract\")), null, 2);\n    }\n}\n\nfunction invalidValue(typ: any, val: any, key: any, parent: any = ''): never {\n    const prettyTyp = prettyTypeName(typ);\n    const parentText = parent ? ` on ${parent}` : '';\n    const keyText = key ? ` for key \"${key}\"` : '';\n    throw Error(`Invalid value${keyText}${parentText}. Expected ${prettyTyp} but got ${JSON.stringify(val)}`);\n}\n\nfunction prettyTypeName(typ: any): string {\n    if (Array.isArray(typ)) {\n        if (typ.length === 2 && typ[0] === undefined) {\n            return `an optional ${prettyTypeName(typ[1])}`;\n        } else {\n            return `one of [${typ.map(a => { return prettyTypeName(a); }).join(\", \")}]`;\n        }\n    } else if (typeof typ === \"object\" && typ.literal !== undefined) {\n        return typ.literal;\n    } else {\n        return typeof typ;\n    }\n}\n\nfunction jsonToJSProps(typ: any): any {\n    if (typ.jsonToJS === undefined) {\n        const map: any = {};\n        typ.props.forEach((p: any) => map[p.json] = { key: p.js, typ: p.typ });\n        typ.jsonToJS = map;\n    }\n    return typ.jsonToJS;\n}\n\nfunction jsToJSONProps(typ: any): any {\n    if (typ.jsToJSON === undefined) {\n        const map: any = {};\n        typ.props.forEach((p: any) => map[p.js] = { key: p.json, typ: p.typ });\n        typ.jsToJSON = map;\n    }\n    return typ.jsToJSON;\n}\n\nfunction transform(val: any, typ: any, getProps: any, key: any = '', parent: any = ''): any {\n    function transformPrimitive(typ: string, val: any): any {\n        if (typeof typ === typeof val) return val;\n        return invalidValue(typ, val, key, parent);\n    }\n\n    function transformUnion(typs: any[], val: any): any {\n        // val must validate against one typ in typs\n        const l = typs.length;\n        for (let i = 0; i < l; i++) {\n            const typ = typs[i];\n            try {\n                return transform(val, typ, getProps);\n            } catch (_) {}\n        }\n        return invalidValue(typs, val, key, parent);\n    }\n\n    function transformEnum(cases: string[], val: any): any {\n        if (cases.indexOf(val) !== -1) return val;\n        return invalidValue(cases.map(a => { return l(a); }), val, key, parent);\n    }\n\n    function transformArray(typ: any, val: any): any {\n        // val must be an array with no invalid elements\n        if (!Array.isArray(val)) return invalidValue(l(\"array\"), val, key, parent);\n        return val.map(el => transform(el, typ, getProps));\n    }\n\n    function transformDate(val: any): any {\n        if (val === null) {\n            return null;\n        }\n        const d = new Date(val);\n        if (isNaN(d.valueOf())) {\n            return invalidValue(l(\"Date\"), val, key, parent);\n        }\n        return d;\n    }\n\n    function transformObject(props: { [k: string]: any }, additional: any, val: any): any {\n        if (val === null || typeof val !== \"object\" || Array.isArray(val)) {\n            return invalidValue(l(ref || \"object\"), val, key, parent);\n        }\n        const result: any = {};\n        Object.getOwnPropertyNames(props).forEach(key => {\n            const prop = props[key];\n            const v = Object.prototype.hasOwnProperty.call(val, key) ? val[key] : undefined;\n            result[prop.key] = transform(v, prop.typ, getProps, key, ref);\n        });\n        Object.getOwnPropertyNames(val).forEach(key => {\n            if (!Object.prototype.hasOwnProperty.call(props, key)) {\n                result[key] = transform(val[key], additional, getProps, key, ref);\n            }\n        });\n        return result;\n    }\n\n    if (typ === \"any\") return val;\n    if (typ === null) {\n        if (val === null) return val;\n        return invalidValue(typ, val, key, parent);\n    }\n    if (typ === false) return invalidValue(typ, val, key, parent);\n    let ref: any = undefined;\n    while (typeof typ === \"object\" && typ.ref !== undefined) {\n        ref = typ.ref;\n        typ = typeMap[typ.ref];\n    }\n    if (Array.isArray(typ)) return transformEnum(typ, val);\n    if (typeof typ === \"object\") {\n        return typ.hasOwnProperty(\"unionMembers\") ? transformUnion(typ.unionMembers, val)\n            : typ.hasOwnProperty(\"arrayItems\")    ? transformArray(typ.arrayItems, val)\n            : typ.hasOwnProperty(\"props\")         ? transformObject(getProps(typ), typ.additional, val)\n            : invalidValue(typ, val, key, parent);\n    }\n    // Numbers can be parsed by Date but shouldn't be.\n    if (typ === Date && typeof val !== \"number\") return transformDate(val);\n    return transformPrimitive(typ, val);\n}\n\nfunction cast<T>(val: any, typ: any): T {\n    return transform(val, typ, jsonToJSProps);\n}\n\nfunction uncast<T>(val: T, typ: any): any {\n    return transform(val, typ, jsToJSONProps);\n}\n\nfunction l(typ: any) {\n    return { literal: typ };\n}\n\nfunction a(typ: any) {\n    return { arrayItems: typ };\n}\n\nfunction u(...typs: any[]) {\n    return { unionMembers: typs };\n}\n\nfunction o(props: any[], additional: any) {\n    return { props, additional };\n}\n\nfunction m(additional: any) {\n    return { props: [], additional };\n}\n\nfunction r(name: string) {\n    return { ref: name };\n}\n\nconst typeMap: any = {\n    \"RentalContract\": o([\n        { json: \"first_name\", js: \"first_name\", typ: \"\" },\n        { json: \"last_name\", js: \"last_name\", typ: \"\" },\n        { json: \"phone_number\", js: \"phone_number\", typ: u(undefined, u(null, \"\")) },\n    ], false),\n};\n"}}},"schema":{"$ref":"#/components/schemas/TemplateModelCode"}}}},"422":{"description":"unknown language","content":{"application/json":{"examples":{"unknown language":{"summary":"unknown language","value":{"error":{"code":"validation_failed","message":"Invalid request: lang must be one of: \"typescript\", \"javascript\", \"ruby\", \"python\", \"php\", \"java\", \"csharp\", \"elixir\", \"go\"","details":[{"code":"enum","message":"must be one of: \"typescript\", \"javascript\", \"ruby\", \"python\", \"php\", \"java\", \"csharp\", \"elixir\", \"go\"","parameter":"lang"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"template not found","content":{"application/json":{"examples":{"template not found":{"summary":"template not found","value":{"error":{"code":"not_found","message":"There's no template with ID tpl_1234567890abcdef09 in this account. Check the ID, and that the API token is from the template's account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/uploads/presign":{"get":{"summary":"Get a presigned URL to upload a file","tags":["Custom Files"],"operationId":"getPresignUrl","description":"Returns a presigned S3 form for uploading a file directly to DocSpring, for files too large to send in a\nrequest body. POST the `fields` and the file (as `file`) to `url` as multipart/form-data, then pass\n`fields.key` as the `cache_id` when you create a custom file.\n","externalDocs":{"url":"https://docspring.com/docs/api-guide/combine-pdfs/","description":"Learn about uploading custom files for PDF combining"},"responses":{"200":{"description":"presigned URL created","content":{"application/json":{"examples":{"presigned URL created":{"summary":"presigned URL created","value":{"fields":{"key":"cache/ed9424dccf185f3835df4e9e1da0ca0b","policy":"eyJleHBpcmF0aW9uIjoiMjAxOS0xMC0wNVQxNDowMDowMFoifQ==","x-amz-credential":"123456789/20191005/us-east-1/s3/aws4_request","x-amz-algorithm":"AWS4-HMAC-SHA256","x-amz-date":"20191005T130000Z","x-amz-signature":"6b715e441bd7ea5beec87f8415230a600be6dfd76b8f89103137618dca959fac"},"headers":{},"method":"post","url":"https://test-bucket.s3.amazonaws.com"}}},"schema":{"$ref":"#/components/schemas/UploadPresign"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks":{"get":{"summary":"List webhooks","tags":["Webhooks"],"operationId":"listWebhooks","description":"Returns the webhooks in your account, newest first, one page at a time. Filter them by event type, mode, or\nthe API token, template or folder they're scoped to.\n","parameters":[{"name":"event_type","in":"query","required":false,"schema":{"title":"WebhookEventType","x-type-description":"An event that a webhook can subscribe to.","type":"string","enum":["submission.processed","submission.failed","submission.declined","signature_request.viewed","signature_request.completed","signature_request.declined","combined_pdf.processed","combined_pdf.failed","submission_batch.processed","submission_batch.failed","submission.created","submission.updated","submission.expired","signature_request.updated","combined_pdf.expired","template.created","template.updated","template.deleted","webhook.created","webhook.updated","webhook.deleted","custom_file.created","folder.created","folder.updated","folder.deleted"]},"description":"Only list webhooks that subscribe to this event.","example":"submission.processed"},{"name":"mode","in":"query","required":false,"schema":{"title":"WebhookMode","x-type-description":"Which submissions a webhook sends events for, test or live.","type":"string","enum":["test","live"]},"description":"Only list webhooks set to this mode."},{"name":"template_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list webhooks scoped to this template.","example":"tpl_1234567890abcdef01"},{"name":"folder_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list webhooks scoped to this folder."},{"name":"api_token_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only list webhooks scoped to this API token."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many items to return (1-100, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The previous page's `next_cursor`, to get the next page. It's the ID of that page's last item, so get the next page before you delete or change the items on this one."}],"responses":{"200":{"description":"webhooks for a template and event","content":{"application/json":{"examples":{"webhooks for a template and event":{"summary":"webhooks for a template and event","value":{"data":[{"id":"whk_1234567890abcdef01","name":"Test Webhook","url":"https://example.com/webhook","enabled":true,"event_types":["submission.processed"],"mode":null,"version":3,"api_token_ids":[],"template_ids":["tpl_1234567890abcdef01"],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{},"consecutive_failures":0,"last_failure_at":null,"disabled_at":null,"disabled_reason":null,"secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}},"webhooks for an event API v2 renamed":{"summary":"webhooks for an event API v2 renamed","value":{"data":[{"id":"whk_1234567890abcdef01","name":"Test Webhook","url":"https://example.com/webhook","enabled":true,"event_types":["combined_pdf.processed","user.created"],"mode":null,"version":3,"api_token_ids":[],"template_ids":[],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{},"consecutive_failures":0,"last_failure_at":null,"disabled_at":null,"disabled_reason":null,"secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/WebhookList"}}}},"422":{"description":"unknown event type","content":{"application/json":{"examples":{"unknown event type":{"summary":"unknown event type","value":{"error":{"code":"validation_failed","message":"Invalid request: event_type must be one of: \"submission.processed\", \"submission.failed\", \"submission.declined\", \"signature_request.viewed\", \"signature_request.completed\", \"signature_request.declined\", \"combined_pdf.processed\", \"combined_pdf.failed\", \"submission_batch.processed\", \"submission_batch.failed\", \"submission.created\", \"submission.updated\", \"submission.expired\", \"signature_request.updated\", \"combined_pdf.expired\", \"template.created\", \"template.updated\", \"template.deleted\", \"webhook.created\", \"webhook.updated\", \"webhook.deleted\", \"custom_file.created\", \"folder.created\", \"folder.updated\", \"folder.deleted\"","details":[{"code":"enum","message":"must be one of: \"submission.processed\", \"submission.failed\", \"submission.declined\", \"signature_request.viewed\", \"signature_request.completed\", \"signature_request.declined\", \"combined_pdf.processed\", \"combined_pdf.failed\", \"submission_batch.processed\", \"submission_batch.failed\", \"submission.created\", \"submission.updated\", \"submission.expired\", \"signature_request.updated\", \"combined_pdf.expired\", \"template.created\", \"template.updated\", \"template.deleted\", \"webhook.created\", \"webhook.updated\", \"webhook.deleted\", \"custom_file.created\", \"folder.created\", \"folder.updated\", \"folder.deleted\"","parameter":"event_type"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook","tags":["Webhooks"],"operationId":"createWebhook","description":"Creates a webhook that sends a POST request to your endpoint whenever a subscribed event happens. Scope it to\nAPI tokens, templates or folders to receive only their events.\n","x-codegen-request-body-name":"body","parameters":[],"responses":{"201":{"description":"webhook created","content":{"application/json":{"examples":{"webhook created":{"summary":"webhook created","value":{"id":"whk_1234567890abcdef01","name":"Test Webhook","url":"https://example.com/webhook","enabled":true,"event_types":["submission.processed","signature_request.completed"],"mode":null,"version":4,"api_token_ids":[],"template_ids":["tpl_1234567890abcdef01"],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{"X-Zapier-Subscription":"123"},"consecutive_failures":0,"last_failure_at":null,"disabled_at":null,"disabled_reason":null,"secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Webhook"}}}},"422":{"description":"invalid webhook","content":{"application/json":{"examples":{"invalid webhook":{"summary":"invalid webhook","value":{"error":{"code":"validation_failed","message":"Invalid request: /event_types/0 must be one of: \"submission.processed\", \"submission.failed\", \"submission.declined\", \"signature_request.viewed\", \"signature_request.completed\", \"signature_request.declined\", \"combined_pdf.processed\", \"combined_pdf.failed\", \"submission_batch.processed\", \"submission_batch.failed\", \"submission.created\", \"submission.updated\", \"submission.expired\", \"signature_request.updated\", \"combined_pdf.expired\", \"template.created\", \"template.updated\", \"template.deleted\", \"webhook.created\", \"webhook.updated\", \"webhook.deleted\", \"custom_file.created\", \"folder.created\", \"folder.updated\", \"folder.deleted\"","details":[{"code":"enum","message":"must be one of: \"submission.processed\", \"submission.failed\", \"submission.declined\", \"signature_request.viewed\", \"signature_request.completed\", \"signature_request.declined\", \"combined_pdf.processed\", \"combined_pdf.failed\", \"submission_batch.processed\", \"submission_batch.failed\", \"submission.created\", \"submission.updated\", \"submission.expired\", \"signature_request.updated\", \"combined_pdf.expired\", \"template.created\", \"template.updated\", \"template.deleted\", \"webhook.created\", \"webhook.updated\", \"webhook.deleted\", \"custom_file.created\", \"folder.created\", \"folder.updated\", \"folder.deleted\"","pointer":"/event_types/0"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"A name for the webhook, shown in the dashboard."},"url":{"type":"string","format":"uri","description":"The endpoint that receives webhook POST requests."},"enabled":{"type":"boolean","description":"Whether DocSpring sends events to the webhook. Webhooks are disabled after repeated failures."},"event_types":{"type":"array","minItems":1,"uniqueItems":true,"description":"The events the webhook subscribes to. A webhook made in the dashboard can also subscribe to API token, account integration and user events, which are listed with their own names.","items":{"title":"WebhookEventType","type":"string","x-type-description":"An event that a webhook can subscribe to.","enum":["submission.processed","submission.failed","submission.declined","signature_request.viewed","signature_request.completed","signature_request.declined","combined_pdf.processed","combined_pdf.failed","submission_batch.processed","submission_batch.failed","submission.created","submission.updated","submission.expired","signature_request.updated","combined_pdf.expired","template.created","template.updated","template.deleted","webhook.created","webhook.updated","webhook.deleted","custom_file.created","folder.created","folder.updated","folder.deleted"]}},"mode":{"title":"WebhookMode","type":["string","null"],"description":"Only send events for test or live submissions. Null sends both.","x-type-description":"Which submissions a webhook sends events for, test or live.","enum":["test","live",null]},"api_token_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events from these API tokens. Combined with the other scope lists using OR. Applies to submission, signature request, combined PDF, submission batch and custom file events."},"template_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for these templates. Combined with the other scope lists using OR. Applies to submission, signature request and template events."},"folder_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for templates in these folders, including their subfolders. Combined with the other scope lists using OR. Applies to submission, signature request, template and folder events."},"include_submission_data":{"type":"boolean","description":"Include the submission's field data in the payload. When false, the submission's data and truncated_text, and each signature request's data, ip_address and user_agent, are null."},"strip_fields":{"type":"array","items":{"type":"string"},"description":"Dot-separated paths to remove from the event's data object. Form fields live under `data` (`data.ssn` removes the ssn field). A bare name removes a top-level key (`metadata` removes the whole metadata object)."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers to send with each request."}},"required":["url","event_types"],"description":"The webhook to create.","additionalProperties":false,"title":"CreateWebhookRequest"},"examples":{"webhook created":{"summary":"webhook created","value":{"name":"Test Webhook","url":"https://example.com/webhook","event_types":["submission.processed","signature_request.completed"],"template_ids":["tpl_1234567890abcdef01"],"headers":{"X-Zapier-Subscription":"123"}}}}}},"required":true,"description":"The webhook to create."}}},"/webhooks/{webhook_id}":{"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook's ID."}],"get":{"summary":"Get a webhook","tags":["Webhooks"],"operationId":"getWebhook","description":"Returns a webhook.","responses":{"200":{"description":"webhook found","content":{"application/json":{"examples":{"webhook found":{"summary":"webhook found","value":{"id":"whk_1234567890abcdef01","name":"Test Webhook","url":"https://example.com/webhook","enabled":true,"event_types":["submission.processed"],"mode":null,"version":3,"api_token_ids":[],"template_ids":[],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{},"consecutive_failures":0,"last_failure_at":null,"disabled_at":null,"disabled_reason":null,"secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Webhook"}}}},"404":{"description":"webhook not found","content":{"application/json":{"examples":{"webhook not found":{"summary":"webhook not found","value":{"error":{"code":"not_found","message":"There's no webhook with ID whk_1234567890abcdef01 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a webhook","tags":["Webhooks"],"operationId":"updateWebhook","description":"Updates a webhook. Only the properties you send change.","x-codegen-request-body-name":"body","parameters":[],"responses":{"200":{"description":"webhook updated","content":{"application/json":{"examples":{"webhook updated":{"summary":"webhook updated","value":{"id":"whk_1234567890abcdef01","name":"Updated Webhook","url":"https://example.com/webhook","enabled":false,"event_types":["submission.processed"],"mode":null,"version":3,"api_token_ids":[],"template_ids":[],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{},"consecutive_failures":0,"last_failure_at":null,"disabled_at":"2018-10-20T09:00:00Z","disabled_reason":"Manually disabled","secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Webhook"}}}},"404":{"description":"webhook not found","content":{"application/json":{"examples":{"webhook not found":{"summary":"webhook not found","value":{"error":{"code":"not_found","message":"There's no webhook with ID whk_1234567890abcdef01 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"invalid webhook","content":{"application/json":{"examples":{"invalid webhook":{"summary":"invalid webhook","value":{"error":{"code":"validation_failed","message":"Invalid request: /template_ids has IDs that aren't in this account: tpl_missing","details":[{"code":"invalid","message":"has IDs that aren't in this account: tpl_missing","pointer":"/template_ids"}],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"A name for the webhook, shown in the dashboard."},"url":{"type":"string","format":"uri","description":"The endpoint that receives webhook POST requests."},"enabled":{"type":"boolean","description":"Whether DocSpring sends events to the webhook. Webhooks are disabled after repeated failures."},"event_types":{"type":"array","minItems":1,"uniqueItems":true,"description":"The events the webhook subscribes to. A webhook made in the dashboard can also subscribe to API token, account integration and user events, which are listed with their own names.","items":{"title":"WebhookEventType","type":"string","x-type-description":"An event that a webhook can subscribe to.","enum":["submission.processed","submission.failed","submission.declined","signature_request.viewed","signature_request.completed","signature_request.declined","combined_pdf.processed","combined_pdf.failed","submission_batch.processed","submission_batch.failed","submission.created","submission.updated","submission.expired","signature_request.updated","combined_pdf.expired","template.created","template.updated","template.deleted","webhook.created","webhook.updated","webhook.deleted","custom_file.created","folder.created","folder.updated","folder.deleted"]}},"mode":{"title":"WebhookMode","type":["string","null"],"description":"Only send events for test or live submissions. Null sends both.","x-type-description":"Which submissions a webhook sends events for, test or live.","enum":["test","live",null]},"api_token_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events from these API tokens. Combined with the other scope lists using OR. Applies to submission, signature request, combined PDF, submission batch and custom file events."},"template_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for these templates. Combined with the other scope lists using OR. Applies to submission, signature request and template events."},"folder_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Only send events for templates in these folders, including their subfolders. Combined with the other scope lists using OR. Applies to submission, signature request, template and folder events."},"include_submission_data":{"type":"boolean","description":"Include the submission's field data in the payload. When false, the submission's data and truncated_text, and each signature request's data, ip_address and user_agent, are null."},"strip_fields":{"type":"array","items":{"type":"string"},"description":"Dot-separated paths to remove from the event's data object. Form fields live under `data` (`data.ssn` removes the ssn field). A bare name removes a top-level key (`metadata` removes the whole metadata object)."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers to send with each request."}},"description":"The settings to change. Properties left out keep their values.","additionalProperties":false,"title":"UpdateWebhookRequest"},"examples":{"webhook updated":{"summary":"webhook updated","value":{"name":"Updated Webhook","enabled":false}}}}},"required":true,"description":"The settings to change. Properties left out keep their values."}},"delete":{"summary":"Delete a webhook","tags":["Webhooks"],"operationId":"deleteWebhook","description":"Deletes a webhook so it stops receiving events, and returns it.","responses":{"200":{"description":"webhook deleted","content":{"application/json":{"examples":{"webhook deleted":{"summary":"webhook deleted","value":{"id":"whk_1234567890abcdef01","name":"Test Webhook","url":"https://example.com/webhook","enabled":true,"event_types":["submission.processed"],"mode":null,"version":3,"api_token_ids":[],"template_ids":[],"folder_ids":[],"include_submission_data":true,"strip_fields":[],"headers":{},"consecutive_failures":0,"last_failure_at":null,"disabled_at":null,"disabled_reason":null,"secret":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","created_at":"2018-10-20T09:00:00Z","updated_at":"2018-10-20T09:00:00Z"}}},"schema":{"$ref":"#/components/schemas/Webhook"}}}},"404":{"description":"webhook not found","content":{"application/json":{"examples":{"webhook not found":{"summary":"webhook not found","value":{"error":{"code":"not_found","message":"There's no webhook with ID whk_1234567890abcdef01 in this account.","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication failed","content":{"application/json":{"examples":{"authentication failed":{"summary":"authentication failed","value":{"error":{"code":"unauthorized","message":"The Authorization header is missing. Send your API token ID and secret with HTTP Basic auth (our client libraries read DOCSPRING_TOKEN_ID and DOCSPRING_TOKEN_SECRET). See https://docspring.com/docs/api-guide/authentication/","details":[],"request_id":"req_1234567890abcdef01"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}