The envelope object
Envelopes are a core part of Magistrate. They represent a collection of documents that can be signed. You can create and send envelopes for signature and you can retrieve and view existing envelopes via the Magistrate API.
The envelope object contains all the information about a particular envelope, such as its unique ID, its status, and the documents it contains. Most endpoints in the Magistrate API respond with an envelope object.
Properties
- Name
id
- Type
- string
- Description
The unique ID of the envelope in UUID4 format.
- Name
name
- Type
- string
- Description
The name of the envelope.
- Name
created_at
- Type
- string
- Description
Date and time the envelope was first created. ISO-8601 formatted string.
- Name
updated_at
- Type
- string
- Description
Latest date and time the envelope was updated. ISO-8601 formatted string.
- Name
sent_at
- Type
- string or null
- Description
Date and time the envelope was sent for signature. ISO-8601 formatted string.
If the envelope has not been sent for signature, this will be
null
.
- Name
status
- Type
- string
- Description
One of
draft
,sent
,partially_executed
,fully_executed
, andcanceled
.An envelope starts in
draft
, and transitions tosent
when it is sent for signature. Once the first party signs, the envelope transitions topartially_executed
. Once all signatures are completed, the envelope transitions tofully_executed
.The signature request can be canceled before the envelope becomes fully executed. If it is so canceled, the envelope will transition to
canceled
.
- Name
source
- Type
- string
- Description
One of
web
,api
, andzapier
. Indicates how the envelope was created.
- Name
parties
- Type
- list of objects
- Description
A list of the parties to the contract. By default, there is one signature per party. But it's possible in some blueprints for a party to have more than one signature in the contract. The SAFE is an example.
Party Object- Name
name
- Type
- string
- Description
The legal name of the party. This can either be the name of a natural person or the name of an entity like a corporation.
- Name
email
- Type
- string
- Description
The email address of the party. If the party is an entity like a corporation, this should be the email address of the authorized signatory.
- Name
is_entity
- Type
- boolean
- Description
If the party to the contract is an entity like a corporation, this will be true. If the party is a human being, this will be false.
- Name
authorized_human
- Type
- object or null
- Description
If
is_entity
istrue
, this object represents the human being that is authorized to sign for the entity. Ifis_entity
isfalse
, this will benull
.Authorized Human Object Expand
- Name
signatures
- Type
- list of objects
- Description
Each party is associated with one or more signature blocks. More than one signature block means that party has to sign in multiple places in the envelope. Signature blocks can either be signed or not signed.
Signature Object Expand
- Name
documents
- Type
- list of objects
- Description
A document contains the actual text of the contract. Every envelope can have one or more documents in it. For simple contracts, an envelope would only have one document. But for more complex contracts, there can be multiple documents bundled together in one envelope.
Document Object- Name
body
- Type
- string
- Description
The text of the document, in plain text format. This text includes signature blocks, whether signed or not.
- Name
txt_url
- Type
- string or null
- Description
URL to download the compiled, fully executed envelope with all documents combined, in plain text format. This link may expire after 24 hours. If the envelope is not fully executed, this will be
null
.
- Name
pdf_url
- Type
- string or null
- Description
URL to download the compiled, fully executed envelope with all documents combined, in PDF format. This link may expire after 24 hours. If the envelope is not fully executed, this will be
null
.
Example envelope object
{
"id": "96833327-8256-4d4d-b04a-3bef8da020e5",
"name": "Bill of Sale",
"created_at": "2022-10-07T13:04:07Z",
"sent_at": "2022-10-07T13:04:07Z",
"status": "fully_executed",
"source": "api",
"parties": [
{
"name": "Harry Khanna",
"email":"harry@getmagistrate.com",
"is_entity": false,
"signatures": [
{
"id": "02409f8c-aae5-40d7-bc33-f481b38e50d8",
"signed_at": "2022-10-08T12:00:04Z",
"signed_ip": "123.4.5.6"
}
]
},
{
"name": "Smith LLC",
"email": "jane@example.com",
"is_entity": true,
"authorized_human": {
"name": "Jane Smith",
"title": "Chief Executive Officer",
},
"signatures": [
{
"id": "fc4b8314-6905-4386-978a-5be259894e3a",
"signed_at": "2022-10-09T11:44:33Z",
"signed_ip": "199.5.4.3"
}
]
}
],
"documents": [
{
"body": "BILL OF SALE\nIn consideration of $30,000.00 paid by Smith LLC (\"Transferee\") to Harry Khanna (\"Transferor\"), Transferor hereby contributes, transfers, conveys and delivers to Transferee all of Transferor's right title and interest in his 2020 Toyota Tacoma (VIN 123456789) (the \"Property\").\n\nThe Property is being sold \"AS IS\" and Transferor explicitly disclaims all warranties, express or implied.\n\nTransferee represents and warrants that she has inspected the Property and accepts the Property in its present condition.\n\nIN WITNESS WHEREOF, Transferee and Transferor have executed this Bill of Sale on the date set forth immediately below their signature. This Bill of Sale is effective as of the latest date set forth below.\n\n/s/ Harry Khanna\nHarry Khanna\n\n\nSMITH LLC\n\nBy: /s/ Jane Smith\nName: Jane Smith\nTitle: Chief Executive Officer"
}
],
"txt_url": "https://secure.getmagistrate.com/sign/envelopes/96833327-8256-4d4d-b04a-3bef8da020e5/download/?access_token=y1ZsVuBRxLMOk6Jp2d63iolHx0xbkQsVTC1sca3MEbc",
"pdf_url": "https://secure.getmagistrate.com/sign/envelopes/96833327-8256-4d4d-b04a-3bef8da020e5/download/?access_token=y1ZsVuBRxLMOk6Jp2d63iolHx0xbkQsVTC1sca3MEbc&format=pdf"
}