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"
}