GET POST
envelopes/
User API Service tier
List envelopes, or create one with POST. derived from route
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/
Service tier https://contracts.mattering.io/api/internal/envelopes/
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 bare JSON object (no envelope)
{
"...": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 invalid_recipients400 title_required400 unsupported_field401 unauthorized404 workspace_not_found
Example
User API Service tier
curl -X GET "https://contracts.mattering.io/api/user/v1/envelopes/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://contracts.mattering.io/api/internal/envelopes/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: ContractsCore/internal_api.py (internal_api.envelopes)
GET
envelopes/{public_id} /
User API Service tier
Read one of the envelopes by id. derived from route
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/{public_id} /
Service tier https://contracts.mattering.io/api/internal/envelopes/{public_id} /
Path parameters
Responses
200 bare JSON object (no envelope)
{
"envelope": {
"public_id": "...",
"id": "...",
"title": "...",
"status": "...",
"space_id": "...",
"enforce_signing_order": "...",
"created_at": "2026-01-01T00:00:00Z",
"sent_at": "2026-01-01T00:00:00Z",
"completed_at": "2026-01-01T00:00:00Z",
"document_count": 0,
"recipient_count": 0,
"has_certificate": true,
"recipients": [
{
"public_id": "...",
"name": "...",
"email": "...",
"role": "...",
"routing_order": "...",
"status": "...",
"signed_at": "2026-01-01T00:00:00Z"
}
],
"contract_document": {
"public_id": "..."
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized404 not_found
Example
User API Service tier
curl -X GET "https://contracts.mattering.io/api/user/v1/envelopes/PUBLIC_ID/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://contracts.mattering.io/api/internal/envelopes/PUBLIC_ID/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: ContractsCore/internal_api.py (internal_api.envelope_detail)
POST
envelopes/{public_id} /documents/
User API Service tier
Attach a Mattering Files document to a draft packet as a PDF, and place the fields its tags ask for. Response: the document, the fields placed, the tags that matched nobody, and the signers still without a signature field.
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/{public_id} /documents/
Service tier https://contracts.mattering.io/api/internal/envelopes/{public_id} /documents/
Path parameters
Body keys (JSON)
Key Required Default
file_idoptional or conditional none place_fieldsoptional or conditional trueroleoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"...": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 file_id_required401 unauthorized404 file_not_found404 not_found409 not_editable502 file_unavailable
Example
User API Service tier
curl -X POST "https://contracts.mattering.io/api/user/v1/envelopes/PUBLIC_ID/documents/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_id": "...",
"place_fields": true,
"role": "..."
}' curl -X POST "https://contracts.mattering.io/api/internal/envelopes/PUBLIC_ID/documents/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"file_id": "...",
"place_fields": true,
"role": "..."
}'
Source: ContractsCore/packet_api.py (packet_api.envelope_documents)
GET
envelopes/{public_id} /events/
User API Service tier
Read one of the envelopes by id. derived from route
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/{public_id} /events/
Service tier https://contracts.mattering.io/api/internal/envelopes/{public_id} /events/
Path parameters
Responses
200 bare JSON object (no envelope)
{
"...": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized404 not_found
Example
User API Service tier
curl -X GET "https://contracts.mattering.io/api/user/v1/envelopes/PUBLIC_ID/events/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://contracts.mattering.io/api/internal/envelopes/PUBLIC_ID/events/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: ContractsCore/internal_api.py (internal_api.envelope_events)
GET POST
envelopes/{public_id} /fields/
User API Service tier
GET: the packet's fields. POST: add fields at explicit coordinates (normalized 0..1, top-left origin, the builder's shape); ``replace`` clears the target document's fields first. Each field names its recipient by number in signing order, email or name.
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/{public_id} /fields/
Service tier https://contracts.mattering.io/api/internal/envelopes/{public_id} /fields/
Path parameters
Body keys (JSON)
Key Required Default
document_idoptional or conditional none fieldsoptional or conditional none replaceoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"...": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 fields_required400 invalid_fields401 unauthorized404 document_not_found404 not_found409 no_documents409 not_editable
Example
User API Service tier
curl -X POST "https://contracts.mattering.io/api/user/v1/envelopes/PUBLIC_ID/fields/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document_id": "...",
"fields": "...",
"replace": "..."
}' curl -X POST "https://contracts.mattering.io/api/internal/envelopes/PUBLIC_ID/fields/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"document_id": "...",
"fields": "...",
"replace": "..."
}'
Source: ContractsCore/packet_api.py (packet_api.envelope_fields)
POST
envelopes/{public_id} /send/
User API Service tier
POST to envelopes/{public_id}/send/. derived from route
URL
User API https://contracts.mattering.io/api/user/v1/envelopes/{public_id} /send/
Service tier https://contracts.mattering.io/api/internal/envelopes/{public_id} /send/
Path parameters
Responses
200 bare JSON object (no envelope)
{
"ok": true,
"envelope": {
"public_id": "...",
"id": "...",
"title": "...",
"status": "...",
"space_id": "...",
"enforce_signing_order": "...",
"created_at": "2026-01-01T00:00:00Z",
"sent_at": "2026-01-01T00:00:00Z",
"completed_at": "2026-01-01T00:00:00Z",
"document_count": 0,
"recipient_count": 0,
"has_certificate": true,
"recipients": [
{
"public_id": "...",
"name": "...",
"email": "...",
"role": "...",
"routing_order": "...",
"status": "...",
"signed_at": "2026-01-01T00:00:00Z"
}
],
"contract_document": {
"public_id": "..."
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized404 not_found
Example
User API Service tier
curl -X POST "https://contracts.mattering.io/api/user/v1/envelopes/PUBLIC_ID/send/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X POST "https://contracts.mattering.io/api/internal/envelopes/PUBLIC_ID/send/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: ContractsCore/internal_api.py (internal_api.envelope_send)