CM.com Dossier API

openapi: 3.2.0
info:
  version: '1'
  title: Sign Dossier API
  description: 'Sign by CM.com offers the ability to have end users sign PDF documents online.


    Before 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. This will grant you access to the sandbox environment.


    *The credentials provided by CM.com are confidential and should be kept secret.*'
servers:
- url: https://api.cm.com/sign/v1
- url: https://api.cm.com/sign-sandbox/v1
security:
- JWT: []
tags:
- name: Dossier
  description: Manage dossier
paths:
  /dossiers:
    post:
      operationId: create_dossier
      summary: Create dossier
      description: Create a new dossier to sign. To be notified of changes to the dossier, subscribe to webhook events. For the event structure see the `Webhook Events` section.
      tags:
      - Dossier
      requestBody:
        description: 'You need to provide one or more file id''s you''ve uploaded previously and add the invitees and fields for the persons that need to sign or review the document(s).


          A dossier owner can be specified, but this is optional.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDossier'
      responses:
        '201':
          description: The newly created dossier. Will return your dossierId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dossier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dossiers/{dossierId}:
    parameters:
    - $ref: '#/components/parameters/DossierId'
    get:
      operationId: get_dossier
      summary: Get dossier
      description: Retrieve a single dossier and all its related information
      tags:
      - Dossier
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dossier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replace_dossier
      summary: Update dossier
      description: Modify a single dossier and its related information
      tags:
      - Dossier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyDossier'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dossier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/InvalidState'
    delete:
      operationId: delete_dossier
      summary: Delete dossier
      description: Remove a single dossier and its related information
      tags:
      - Dossier
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dossier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dossiers/{dossierId}/download:
    get:
      operationId: download_dossier
      summary: Download signed files
      description: 'Download a ZIP file containing the complete result of a dossier. The ZIP file will include the PDF files and audit report.


        You can also download the PDF file(s) and audit report separately by using the `type` query parameter'
      tags:
      - Dossier
      parameters:
      - $ref: '#/components/parameters/DossierId'
      - $ref: '#/components/parameters/DownloadType'
      - $ref: '#/components/parameters/DownloadFile'
      responses:
        '200':
          description: A ZIP or PDF file
          content:
            application/zip:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/InvalidState'
  /dossiers/{dossierId}/fields/{fieldId}/value:
    parameters:
    - $ref: '#/components/parameters/DossierId'
    - $ref: '#/components/parameters/FieldId'
    get:
      operationId: get_field_value
      summary: Get field value
      description: Retrieve the field value.
      tags:
      - Dossier
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldValue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dossiers/{dossierId}/fieldvalues:
    parameters:
    - $ref: '#/components/parameters/DossierId'
    get:
      operationId: list_field_values
      summary: Gets all field values
      description: Returns the field values for fields of type checkbox, label, radio, text, and textarea
      tags:
      - Dossier
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FieldIdFieldValue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DossierOwnerId:
      $ref: '#/components/schemas/DossierOwnerReference'
      readOnly: true
    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
    DossierId:
      $ref: '#/components/schemas/DossierReference'
      readOnly: true
    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
    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
    FieldIdFieldValue:
      allOf:
      - type: object
        properties:
          field:
            $ref: '#/components/schemas/FieldId'
      - $ref: '#/components/schemas/FieldValue'
    FieldValue:
      title: FieldValue
      type: object
      properties:
        type:
          type: string
          enum:
          - boolean
          - integer
          - text
          description: The field value type
          examples:
          - text
          readOnly: true
        value:
          type:
          - boolean
          - integer
          - string
          description: The value of the field
          examples:
          - Example
          readOnly: true
    ModifyDossier:
      allOf:
      - $ref: '#/components/schemas/DossierBase'
      - type: object
        properties:
          owners:
            type: array
            items:
              $ref: '#/components/schemas/ModifyDossierOwner'
          files:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/ModifyFile'
          invitees:
            type: array
            items:
              $ref: '#/components/schemas/ModifyInvitee'
          attachments:
            type: array
            minItems: 0
            items:
              $ref: '#/components/schemas/ModifyFile'
    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
    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.
    CreateInvitee:
      $ref: '#/components/schemas/InviteeBase'
    ModifyDossierOwner:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/DossierOwnerReference'
        required:
        - id
      - $ref: '#/components/schemas/DossierOwnerBase'
    ModifyInvitee:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/InviteeReference'
        required:
        - id
      - $ref: '#/components/schemas/InviteeBase'
    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`

            '
          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
    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
    InviteeId:
      $ref: '#/components/schemas/InviteeReference'
      readOnly: true
    FileReference:
      type: string
      format: uuid
      description: A unique reference number for this file.
      examples:
      - 8d817359-7eb8-4b6e-9030-17ac286b7dc0
    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.
    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.
    FieldReference:
      type: string
      format: uuid
      description: Unique Id of a field
      examples:
      - 50ee1534-6172-4228-84e8-653c6f65eaf0
    CreateDossier:
      allOf:
      - $ref: '#/components/schemas/DossierBase'
      - type: object
        properties:
          archive:
            type: boolean
            default: false
            description: This determines if the dossier needs to be archived.
          files:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/CreateFile'
          attachments:
            type: array
            minItems: 0
            items:
              $ref: '#/components/schemas/CreateFile'
          owners:
            type: array
            items:
              $ref: '#/components/schemas/CreateDossierOwner'
          invitees:
            type: array
            items:
              $ref: '#/components/schemas/CreateInvitee'
          template:
            type:
            - string
            - 'null'
            format: uuid
            description: Create a dossier from a template. This means that files and field positions are automatically copied from the template. You can find the template ID in the dashboard.
            default: null
            examples:
            - 06c2e210-54a8-417f-adf2-fc767c31c929
          templateLabelValues:
            type: object
            description: Key-value pairs for template labels. The key must match the exact value of the predefined label in the template. It will then be overwritten by the value in the request.
            additionalProperties:
              type: string
              description: The value corresponding to the key.
        required:
        - name
        - files
    FileId:
      $ref: '#/components/schemas/FileReference'
      readOnly: true
    AttachmentId:
      $ref: '#/components/schemas/FileReference'
      readOnly: true
    FieldType:
      type: string
      description: The type of field for the invitee.
      enum:
      - signature
      - signatureDate
      - initials
      - text
      - textarea
      - label
      - checkbox
      - radio
      - stamp
      examples:
      - signature
    CreateDossierOwner:
      $ref: '#/components/schemas/DossierOwnerBase'
    DossierOwner:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/DossierOwnerId'
        required:
        - id
      - $ref: '#/components/schemas/DossierOwnerBase'
    File:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/FileId'
        required:
        - id
      - $ref: '#/components/schemas/FileBase'
    CreateFile:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/FileReference'
        required:
        - id
      - $ref: '#/components/schemas/FileBase'
    DossierOwnerReference:
      type: string
      format: uuid
      description: Unique Id of the person who created and manages the dossier
      examples:
      - c2b0ff41-f97a-421d-a4eb-85b158a2de2a
    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.
    FieldId:
      $ref: '#/components/schemas/FieldReference'
      readOnly: true
    Invitee:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/InviteeId'
        required:
        - id
      - $ref: '#/components/schemas/InviteeBase'
    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
    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
    ModifyFile:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/FileReference'
        required:
        - id
      - $ref: '#/components/schemas/FileBase'
    DossierReference:
      type: string
      format: uuid
      description: Id of the dossier
      examples:
      - 22470767-904e-4553-9586-d7ed4f2b330e
    Field:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/FieldId'
        required:
        - id
      - $ref: '#/components/schemas/FieldBase'
    Attachment:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/AttachmentId'
        required:
        - id
      - $ref: '#/components/schemas/AttachmentBase'
    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
    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
  parameters:
    DossierId:
      name: dossierId
      in: path
      schema:
        type: string
        format: uuid
      required: true
      description: 'a uuid string that identifies a dossier

        '
      example: 22470767-904e-4553-9586-d7ed4f2b330e
    DownloadType:
      name: type
      in: query
      schema:
        type: string
        enum:
        - zip
        - file
        - auditReport
      required: false
      description: 'Specify the download type. Defaults to `zip`

        '
      example: zip
    DownloadFile:
      name: file
      in: query
      schema:
        type: string
        format: uuid
      required: false
      description: 'When a dossiers has multiple files and download type is `file` you must specify which file to download.


        This parameter will match the `id` of a file object


        When there is only one document per dossier you can omit this parameter and it will automatically determine the file to download.

        '
    FieldId:
      name: fieldId
      in: path
      schema:
        type: string
        format: uuid
      required: true
      description: 'a uuid string that identifies a field

        '
      example: cb222836-fd18-4ec5-8283-63ca2cd2dc0f
  responses:
    InvalidState:
      description: The request cannot be made because the state of the dossier does not match the state that is expected for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
  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.


        The generated token needs to be passed via the HTTP Authorization header like:


        ```

        Authorization: Bearer GENERATED_TOKEN_HERE

        ```


        There 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)

        '