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, and canceled.
An envelope starts in draft, and transitions to sent when it is sent for signature. Once the first party signs, the envelope transitions to partially_executed. Once all signatures are completed, the envelope transitions to fully_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, and zapier. 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 is true, this object represents the human being that is authorized to sign for the entity. If is_entity is false, this will be null.
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"
}