# Get dossier

Retrieve a single dossier and all its related information

# OpenAPI definition

````json
{
  "openapi": "3.1.1",
  "servers": [
    {
      "url": "https://api.cm.com/sign/v1"
    },
    {
      "url": "https://api.cm.com/sign-sandbox/v1"
    }
  ],
  "security": [
    {
      "JWT": []
    }
  ],
  "info": {
    "version": "1",
    "title": "Sign API",
    "description": "Sign by CM.com offers the ability to have end users sign PDF documents online.\n\nBefore you can start using the API, you need to be provided with credentials. You will have received these credentials, consisting of a Key and a Key Id, when you registered for Sign. If you have not yet received any credentials, you can request them via [this link](https://www.cm.com/app/verification-registration/sign). This will grant you access to the sandbox environment.\n\n*The credentials provided by CM.com are confidential and should be kept secret.*\n"
  },
  "tags": [
    {
      "name": "Dossier",
      "description": "Manage dossier"
    }
  ],
  "paths": {
    "/dossiers/{dossierId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/DossierId"
        }
      ],
      "get": {
        "operationId": "get_dossier",
        "summary": "Get dossier",
        "description": "Retrieve a single dossier and all its related information\n",
        "tags": [
          "Dossier"
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dossier"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "The specified resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "parameters": {
      "DossierId": {
        "name": "dossierId",
        "in": "path",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "required": true,
        "description": "a uuid string that identifies a dossier\n",
        "example": "22470767-904e-4553-9586-d7ed4f2b330e"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "title": "Error Response",
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "Response status code, should match HTTP error code"
          },
          "message": {
            "type": "string",
            "description": "High level description of the error that occurred. This description, when present, can be shown to the end user. It might describe that the system is not available, or that an unexpected error occurred. In test mode, the API will return more information (targeted at the developer) here than in production mode."
          }
        }
      },
      "FileId": {
        "$ref": "#/components/schemas/FileReference",
        "readOnly": true
      },
      "AttachmentId": {
        "$ref": "#/components/schemas/FileReference",
        "readOnly": true
      },
      "FileReference": {
        "type": "string",
        "format": "uuid",
        "description": "A unique reference number for this file.",
        "examples": [
          "8d817359-7eb8-4b6e-9030-17ac286b7dc0"
        ]
      },
      "FileBase": {
        "title": "File",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Original name of the file without extension",
            "maxLength": 255,
            "examples": [
              "Purchase contract"
            ]
          },
          "hash": {
            "type": "string",
            "description": "A sha256 hash of the document",
            "maxLength": 64,
            "readOnly": true
          },
          "uploadDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "The time at which the file was uploaded",
            "readOnly": true
          },
          "size": {
            "type": "integer",
            "description": "The size of the file in bytes",
            "examples": [
              3028
            ]
          },
          "contentType": {
            "type": "string",
            "description": "The content type identifying the type of file",
            "examples": [
              "application/pdf"
            ],
            "readOnly": true
          }
        },
        "required": [
          "name",
          "hash",
          "uploadDateTime",
          "contentType"
        ]
      },
      "AttachmentBase": {
        "title": "Attachment",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Original name of the attachment without extension",
            "maxLength": 255,
            "examples": [
              "Attachment v1"
            ]
          },
          "hash": {
            "description": "A sha256 hash of the attachment",
            "maxLength": 64,
            "readOnly": true
          },
          "uploadDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "The time at which the attachment was uploaded",
            "readOnly": true
          },
          "contentType": {
            "type": "string",
            "description": "The content type identifying the type of attachment",
            "examples": [
              "application/pdf"
            ],
            "readOnly": true
          }
        }
      },
      "File": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/FileId"
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/FileBase"
          }
        ]
      },
      "Attachment": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/AttachmentId"
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/AttachmentBase"
          }
        ]
      },
      "DossierId": {
        "$ref": "#/components/schemas/DossierReference",
        "readOnly": true
      },
      "DossierReference": {
        "type": "string",
        "format": "uuid",
        "description": "Id of the dossier",
        "examples": [
          "22470767-904e-4553-9586-d7ed4f2b330e"
        ]
      },
      "Locale": {
        "type": "string",
        "enum": [
          "de-DE",
          "en-US",
          "es-ES",
          "fr-FR",
          "hu-HU",
          "it-IT",
          "ja-JP",
          "nl-NL",
          "pl-PL",
          "pt-PT",
          "ro-RO",
          "sk-SK"
        ],
        "default": "en-US"
      },
      "DossierBase": {
        "title": "Dossier",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DossierId"
          },
          "name": {
            "type": "string",
            "description": "human readable name for this dossier",
            "maxLength": 255,
            "examples": [
              "Purchase contract"
            ]
          },
          "state": {
            "$ref": "#/components/schemas/DossierState",
            "readOnly": true
          },
          "locale": {
            "$ref": "#/components/schemas/Locale",
            "description": "Locale of the language to be used in the dossier"
          },
          "completed": {
            "type": "boolean",
            "examples": [
              false
            ],
            "description": "If the dossier is marked as complete",
            "readOnly": true
          },
          "prepare": {
            "type": [
              "boolean",
              "null"
            ],
            "examples": [
              false
            ],
            "description": "Place fields using the web interface"
          },
          "prepareReturnUrl": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "https://example.com"
            ],
            "description": "Optionally redirect the user to your website after the fields are placed. The url must begin with https://"
          },
          "prepareUrl": {
            "type": "string",
            "examples": [
              "https://www.cm.com/app/sign/prepare/00f00a..."
            ],
            "description": "The URL to the web interface to place fields. The URL is only valid for 60 minutes. Only available when the dossier has been created with `prepare`: `true`\n",
            "readOnly": true
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ],
            "description": "The identifier of a time zone in the IANA database. This will change the time zone of dates used in communication to the recipient and dossier owner. By default Etc/UTC is used when no value is set.",
            "examples": [
              "Europe/Amsterdam"
            ]
          },
          "expiresIn": {
            "type": "integer",
            "format": "int32",
            "minimum": 60,
            "maximum": 7776000,
            "examples": [
              2592000
            ],
            "default": 2592000,
            "description": "The expiry in seconds since the dossier was created"
          },
          "reminderIn": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 86400,
            "maximum": 7776000,
            "examples": [
              604800
            ],
            "description": "The time in seconds after the invite was sent to an invitee, after which an automatic reminder will be sent. Reminders only work if the invite emails were sent by Sign. To cancel all reminders for an existing dossier set value to `null`"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date the dossier expires",
            "readOnly": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date the dossier was created",
            "readOnly": true
          }
        },
        "required": [
          "name"
        ]
      },
      "Dossier": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DossierBase"
          },
          {
            "type": "object",
            "properties": {
              "owners": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DossierOwner"
                }
              },
              "files": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/File"
                }
              },
              "attachments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Attachment"
                }
              },
              "invitees": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Invitee"
                }
              }
            },
            "required": [
              "state",
              "locale",
              "completed",
              "files",
              "invitees"
            ]
          }
        ]
      },
      "DossierState": {
        "type": "string",
        "enum": [
          "draft",
          "pending",
          "completed",
          "declined",
          "expired",
          "deleted"
        ],
        "examples": [
          "pending"
        ],
        "description": "Every dossier is initialized with the draft state. When the dossier is pending, it will have sent out any invitations for signing. From this point, the dossier is mostly no longer editable. Once everyone has signed, the state becomes completed and the signed dossier will be ready for retrieval. If any invitee declines, the state of the dossier will become declined. After the dossier expiry time has passed, a dossier will always enter the expired state. In the expired state a dossier can no longer be completed or declined. Once the state is deleted the signed contracts are no longer downloadable and all contracts and sensitive information are removed from the system."
      },
      "InviteeId": {
        "$ref": "#/components/schemas/InviteeReference",
        "readOnly": true
      },
      "InviteeReference": {
        "description": "Optional. Indicates that only a particular invitee is allowed/required to use a field.",
        "type": "string",
        "format": "uuid",
        "examples": [
          "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84"
        ]
      },
      "InviteeBase": {
        "title": "Invitee",
        "description": "An invitee is someone who has been invited to review and/or sign the dossier.",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the person invited to read and/or sign the document",
            "maxLength": 255,
            "examples": [
              "Peter Invitee"
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "A valid email address",
            "maxLength": 255
          },
          "locale": {
            "$ref": "#/components/schemas/Locale",
            "description": "Locale of the language to be used in invitations.",
            "nullable": true
          },
          "position": {
            "type": "integer",
            "description": "Set the order of signing. For example if there are two invitees set position `1` for the first invitee and position `2` for the second invitee. It is possible to set multiple invitees on the same position. Make sure there is no gap between the positions.",
            "examples": [
              1
            ]
          },
          "authenticationMethods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "otp_sms",
                "otp_email",
                "otp_whatsapp",
                "otp_voice"
              ],
              "description": "Additional user authentication is required before the user can view the dossier. Please note that this is only available when configured for your account."
            }
          },
          "identificationMethod": {
            "$ref": "#/components/schemas/IdentificationMethod",
            "deprecated": true
          },
          "identificationMethods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IdentificationMethod"
            }
          },
          "notifications": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "enum": [
                "invite",
                "signed",
                "reviewed",
                "declined",
                "completed"
              ],
              "description": "Determines which notifications should be sent over the configured channel. By default all notifications are sent."
            }
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            },
            "description": "Additional payment is required. Please note that this is only available when configured for your account."
          },
          "phoneNumber": {
            "type": "string",
            "description": "The phone number of the invitee in E.164 format. Required when identificationMethod is otp.",
            "examples": [
              "+31601234567"
            ]
          },
          "reference": {
            "type": "string",
            "description": "A reference to an external identifier of your invitee.",
            "maxLength": 255,
            "examples": [
              "6c38955e-7324-41e7-97dd-0bcf55e275e2"
            ]
          },
          "readOnly": {
            "type": "boolean",
            "description": "Indicates that this invitee needs to review the dossier, instead of signing it",
            "default": false
          },
          "state": {
            "type": "string",
            "enum": [
              "approved",
              "declined"
            ],
            "description": "The invitee has approved or declined the dossier"
          },
          "stateComment": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the invitee declined the dossier this field may contain the reason for declining.",
            "default": null,
            "readOnly": true,
            "examples": [
              null
            ]
          },
          "stateChanged": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The date the invitee state has changed",
            "default": null,
            "readOnly": true,
            "examples": [
              null
            ]
          },
          "redirectUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "url",
            "description": "URL to redirect the invitee to after signing, approving or declining the dossier. If not set, the default confirmation page will be shown.",
            "default": null
          },
          "fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Field"
            }
          }
        },
        "required": [
          "name"
        ]
      },
      "Invitee": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/InviteeId"
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/InviteeBase"
          }
        ]
      },
      "DossierOwnerId": {
        "$ref": "#/components/schemas/DossierOwnerReference",
        "readOnly": true
      },
      "DossierOwnerReference": {
        "type": "string",
        "format": "uuid",
        "description": "Unique Id of the person who created and manages the dossier",
        "examples": [
          "c2b0ff41-f97a-421d-a4eb-85b158a2de2a"
        ]
      },
      "DossierOwnerBase": {
        "title": "Owner",
        "type": "object",
        "description": "A person who is the creator and owner of the dossier. This person will receive emails of certain events and will receive a copy of the signed dossier.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the person who created the dossier",
            "maxLength": 255,
            "examples": [
              "Mike Dossierowner"
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "A valid email address",
            "maxLength": 255
          },
          "cc": {
            "type": "boolean",
            "description": "When set to `true` the owner will be added to the cc field in email communication.",
            "default": false
          },
          "notifications": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "enum": [
                "signed",
                "reviewed",
                "declined",
                "completed",
                "expired",
                "invite.expired",
                "invite.undelivered",
                "reassigned"
              ],
              "description": "Determines which notifications should be sent to the dossier owner. By default all notifications are sent."
            },
            "examples": [
              null
            ]
          }
        },
        "required": [
          "name",
          "email"
        ]
      },
      "DossierOwner": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/DossierOwnerId"
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/DossierOwnerBase"
          }
        ]
      },
      "FieldId": {
        "$ref": "#/components/schemas/FieldReference",
        "readOnly": true
      },
      "FieldReference": {
        "type": "string",
        "format": "uuid",
        "description": "Unique Id of a field",
        "examples": [
          "50ee1534-6172-4228-84e8-653c6f65eaf0"
        ]
      },
      "FieldType": {
        "type": "string",
        "description": "The type of field for the invitee.",
        "enum": [
          "signature",
          "signatureDate",
          "initials",
          "text",
          "textarea",
          "label",
          "checkbox",
          "radio",
          "stamp"
        ],
        "examples": [
          "signature"
        ]
      },
      "FieldBase": {
        "title": "Field",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/FieldType"
          },
          "required": {
            "type": "boolean",
            "examples": [
              true
            ],
            "default": true,
            "description": "Indicates if the field is required and must be filled in by the user. When required is `true` and type is `checkbox` the field must be checked. For the `checkbox` type, the default value is `false`."
          },
          "file": {
            "$ref": "#/components/schemas/FileReference"
          },
          "tag": {
            "type": "string",
            "examples": [
              "{signature1}"
            ],
            "maxLength": 64,
            "description": "The tag acts as a placeholder; the range and locations of the field are automatically determined based on the location(s) of the tag in the document. Add the tag to every page the field should include in case of initials. The tag should be hidden, for example by making it white."
          },
          "tagRequired": {
            "type": "boolean",
            "examples": [
              true
            ],
            "default": true,
            "description": "Indicates if the tag must be present in the document. When this is set to `false` and the tag is not found in the document it will skip this field."
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldLocation"
            }
          },
          "invitee": {
            "$ref": "#/components/schemas/InviteeReference",
            "readOnly": true
          }
        },
        "required": [
          "type",
          "file"
        ]
      },
      "FieldLocation": {
        "type": "object",
        "properties": {
          "range": {
            "type": "string",
            "pattern": "^\\d+(-\\d+)?$",
            "maxLength": 64,
            "description": "The page number within the PDF that this field occupies (e.g. `1`), or range for a initials field (e.g. `1-3`).",
            "examples": [
              "1"
            ]
          },
          "x": {
            "type": "number",
            "format": "float",
            "description": "X position of the field in points."
          },
          "y": {
            "type": "number",
            "format": "float",
            "description": "Y position of the field in points."
          },
          "width": {
            "type": "number",
            "format": "float",
            "description": "Width of the field in points."
          },
          "height": {
            "type": "number",
            "format": "float",
            "description": "Height of the field in points."
          }
        }
      },
      "Field": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/FieldId"
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/FieldBase"
          }
        ]
      },
      "Payment": {
        "title": "Payment",
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer",
            "description": "The payment amount in cents",
            "minimum": 1,
            "examples": [
              100
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR"
            ],
            "description": "The payment currency"
          }
        },
        "required": [
          "amount",
          "currency"
        ]
      },
      "IdentificationMethod": {
        "type": "string",
        "enum": [
          "idin",
          "iban",
          "otp_sms",
          "otp_email",
          "otp_whatsapp",
          "otp_voice",
          "qualified"
        ],
        "examples": [
          "idin"
        ],
        "description": "Additional user identification is required. When you select `qualified` it cannot be used with other identification methods. Please note that this is only available when configured for your account."
      }
    },
    "securitySchemes": {
      "JWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "In order to authenticate you need to use your credentials to generate a JWT Bearer token. The [JWT token](https://jwt.io/introduction/) has to be generated using the `HS256` algorithm and your credentials. This JWT has to contain the following attributes: `iat`, `nbf`, `exp`  in the payload, as well as the attribute `kid` in the header of the JWT. This `kid` attribute needs to contain the Key Id of your credentials.\n\nThe generated token needs to be passed via the HTTP Authorization header like:\n\n```\nAuthorization: Bearer GENERATED_TOKEN_HERE\n```\n\nThere are many libraries available for different programming languages that can help you to generate a JWT. See the Libraries tab on [https://jwt.io](https://jwt.io)\n"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 106,
      "1": 177,
      "2": 26,
      "3": 196,
      "4": 252,
      "5": 46,
      "6": 219,
      "7": 163,
      "8": 234,
      "9": 51,
      "10": 132,
      "11": 96
    }
  }
}
````