Templates
Send the same document again and again: list your templates, inspect their roles and create envelopes by filling each role.
Templates and roles
A template is a document prepared once on the website — fields placed, message written — with roles instead of people: “Client”, “Company”, “Witness”. To send it, you say who fills each role. Build and edit templates in Templates on the website; the API lists them and creates envelopes from them.
You can use your own templates and the ones your team shares with you. Both reading and using templates need the right scopes: templates:read to list them, and templates:write plus envelopes:write to create envelopes.
Find a template
GET/v1/templates returns templates with their roles (search by title with search); GET/v1/templates/{id} adds the fields, which reference roles by role_name.
curl https://signkoi.com/api/v1/templates/3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16 \
-H "Authorization: Bearer $SIGNKOI_API_KEY"{
"object": "template",
"id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16",
"title": "Mutual NDA",
"description": "Two-party non-disclosure agreement.",
"roles": [
{
"role_name": "Client",
"role": "signer",
"routing_order": 1
},
{
"role_name": "Company",
"role": "signer",
"routing_order": 2
}
],
"field_count": 6,
"page_count": 2,
"shared_with_team": true,
"uses": 41,
"created_at": "2026-08-02T11:20:00Z",
"updated_at": "2026-10-28T16:45:13Z",
"fields": [
{
"object": "field",
"id": "48213",
"type": "signature",
"page": 1,
"x": 0.12,
"y": 0.82,
"width": 0.3,
"height": 0.06,
"required": true,
"label": null,
"placeholder": null,
"options": null,
"group_name": null,
"default_value": null,
"validation": null,
"formula": null,
"read_only": false,
"font_size": null,
"role_name": "Client"
}
]
}Create an envelope from a template
POST/v1/templates/{id}/envelopes fills each role with a person and sends the envelope right away (pass send: false for a draft). The response is the new envelope, like POST /v1/envelopes.
curl -X POST https://signkoi.com/api/v1/templates/3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16/envelopes \
-H "Authorization: Bearer $SIGNKOI_API_KEY" \
-H "Idempotency-Key: 5f1d7c1e-0b8a-4c2e-9f3d-61a2b7e4c905" \
-H "Content-Type: application/json" \
-d '{
"title": "Mutual NDA — Patel Consulting",
"roles": [
{
"role_name": "Client",
"name": "Maya Patel",
"email": "maya@example.com",
"verification": "email_otp"
},
{
"role_name": "Company",
"name": "Rina Koh",
"email": "rina@acme.example"
}
],
"metadata": {
"crm_deal_id": "D-10492"
},
"expires_in_days": 7
}'Quota and failures
Each envelope counts against the monthly allowance. If sending fails, the draft is deleted and the allowance refunded, so a failed call leaves nothing behind.