Send an Existing Template

Overview

This endpoint allows you to use a template via the API.

To get started, you will need to set who the signers are, name & email. You must set a signer for each role you have created.

Setting a signer also updates any name and email fields
Fields of the type datesigned will automatically update when the signer signs.
A signer must have a valid email and name
Reminder days is counted in days from the document was sent
eg 1 day = 24 hours from send
Duplicate (manual templates) - is always true. Duplicate template and send
Duplicate (API uploaded PDFs) - false, API consumes template and sends it. Set duplicate=true to send this document to a batch of people
You can pre-fill in form inputs and labels (eg title, role, company etc) by setting the fields array in the JSON.
You can rename the main document using 'doc_name', to rename the extra documents (attachments), use 'attachment_names_in_order'
Use the metadata field for any custom data, arrays or objects
Any json node that starts info_ is purely for information below, you can ommit it from you request
ignore_missing_signers (optional) - if set to true, any extra signers found in your document will be removed when the template is used.

You can find the OpenAPI 3.1 specification for the JSON parameters on goodsign.stoplight.io

End Point

https://goodsign.io/api/usetemplate

Method

POST

Authentication

Bearer your_api_token

Send the invite yourself

Embedded signing

By default we email each signer their signing link. Add email_external to your payload to take that over yourself — useful if you want the signer to stay inside your own app, or if the invite should come from your own system.

email_external: true — we send the signer nothing at all. Not the signing request, and not the completed document once it is signed. Everything is yours to send.
email_external: "notifyonly" — we skip the signing request, but we still email the signer the finished PDF when the document completes.

Either way the response gains a signing_links array, one entry per signer:

{
  "success": true,
  "signing_links": [
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "link": "https://goodsign.io/sign/start/abc123",
      "key": "signer1"
    }
  ]
}

Put that link in an email of your own, or load it in an iframe so the signer never leaves your app. Two URL forms are available:

/sign/start/{id} — shows the GoodSign welcome screen first (this is what signing_links returns)
/sign/reviewdoc/{id} — drops the signer straight into the signing experience

When embedding, we post the message SIGN_COMPLETE to the parent window once the signer finishes, so you can redirect or close the frame. Download our example iFrame HTML to get started.

Give the iframe a real height — a pixel height, a vh, or a flexed container. If the height resolves to auto (height="100%" on a page whose body has no height) iOS Safari grows the frame to the full height of the document inside it instead of scrolling within the frame, and the signature pad ends up off-screen on long documents.

Note: our reminder endpoints will not email a signer you have marked external — chasing them is yours to do too. Resending from the dashboard still sends.

Example JSON PayLoad
Set signers

{
    "uuid": null,
    "doc_name": "F - Depreciation Schedule.pdf",
    "attachment_names_in_order": [],
    "metadata": [
        "any valid json works"
    ],
    "webhook": "",
    "cc_email": "",
    "smsverify(optional)": "boolean true or false",
    "send_in_order(optional)": "boolean true or false",
    "duplicate(optional)": "boolean default true for manually created template, false for PDFs loaded via api",
    "email_subject(optional)": "{fullname} has requested your signature on {docname}",
    "email_message(optional)": "extra message to include, not required",
    "ignore_missing_signers(optional)": false,
    "fields(optional)": []
}

Working Curl Request

Uses JSON and signers from above.
(excludes fields, metadata, webhook)

curl --request POST \
--url https://goodsign.io/api/usetemplate \
--header 'authorization: Bearer YOUR_API_TOKEN' \
--data '{"uuid":null,"doc_name":"F - Depreciation Schedule.pdf","attachment_names_in_order":[],"metadata":["any valid json works"],"webhook":"","cc_email":"","smsverify(optional)":"boolean true or false","send_in_order(optional)":"boolean true or false","duplicate(optional)":"boolean default true for manually created template, false for PDFs loaded via api","email_subject(optional)":"{fullname} has requested your signature on {docname}","email_message(optional)":"extra message to include, not required","ignore_missing_signers(optional)":false}'

Send template