Charthop Signature Request API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop Signature Request API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: Signature Request
paths:
  /v1/org/{orgId}/signature-request:
    get:
      tags:
      - Signature Request
      summary: Return signature requests
      operationId: findSignatureRequests
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: requestUserId
        in: query
        description: Filter by signature requests requested by an individual
        required: false
        schema:
          type: string
      - name: signUserId
        in: query
        description: Filter by signature requests requested for signature of an individual
        required: false
        schema:
          type: string
      - name: fromCreateAt
        in: query
        description: Filter by signature requests requested from a particular timestamp
        required: false
        schema:
          type: string
      - name: untilCreateAt
        in: query
        description: Filter by signature requests requested up until a particular timestamp
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Signature request id to start from, when paginating
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsSignatureRequest'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/signature-request/file/{fileId}:
    get:
      tags:
      - Signature Request
      summary: Retrieve an individual signature request on an existing file
      operationId: getSignatureRequestForFile
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        description: File identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequest'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - Signature Request
      summary: Create a new signature request on a file
      operationId: createSignatureRequestForFile
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        description: File identifier
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSignatureRequestRequest'
        required: true
  /v1/org/{orgId}/signature-request/usage:
    get:
      tags:
      - Signature Request
      summary: Retrieve current signature request usage for the organization
      operationId: getSignatureRequestUsage
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequestUsageResponse'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/signature-request/{id}:
    get:
      tags:
      - Signature Request
      summary: Retrieve an individual signature request
      operationId: getSignatureRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Filter by signature requests requested by an individual
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureRequest'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/signature-request/{id}/cancel:
    post:
      tags:
      - Signature Request
      summary: Cancel an existing signature request
      operationId: cancelSignatureRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The signature request id to cancel
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/signature-request/{id}/decline:
    post:
      tags:
      - Signature Request
      summary: Decline to sign a signature request
      operationId: declineSignatureRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The signature request id to decline
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignRequest'
        required: true
  /v1/org/{orgId}/signature-request/{id}/external-url:
    get:
      tags:
      - Signature Request
      summary: Retrieve an individual signature request's signing URL if using an external…
      operationId: getSignatureRequestExternalUrl
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Signature request ID
        required: true
        schema:
          type: string
      - name: redirectPath
        in: query
        description: Redirect path to send user to when signature is complete
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalSignUrlResponse'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/signature-request/{id}/sign:
    post:
      tags:
      - Signature Request
      summary: Sign a signature request
      operationId: signSignatureRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The signature request id to sign
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignRequest'
        required: true
  /v1/org/{orgId}/signature-request/{id}/signature:
    get:
      tags:
      - Signature Request
      summary: Retrieve all of the signatures relating to a signature request
      operationId: findSignaturesOnSignatureRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Filter by signature requests requested by an individual
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsSignature'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
components:
  schemas:
    AccessAction:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        fields:
          type: array
          uniqueItems: true
          items:
            type: string
        types:
          type: array
          uniqueItems: true
          items:
            type: string
    SignatureRequestUsageResponse:
      type: object
      required:
      - signatureRequestCount
      - qesSignatureRequestCount
      - qesSignatureRequestsLimit
      - nextPeriodStartDate
      properties:
        signatureRequestCount:
          type: integer
          format: int32
        qesSignatureRequestCount:
          type: integer
          format: int32
        qesSignatureRequestsLimit:
          type: integer
          format: int32
        nextPeriodStartDate:
          type: string
          format: date
    MessageChannelConfig:
      type: object
      required:
      - channels
      - alwaysEmail
      properties:
        channels:
          type: array
          items:
            type: string
            enum:
            - EMAIL
            - CHAT
            - CHAT_SLACK
            - CHAT_TEAMS
        alwaysEmail:
          type: boolean
    SignatureBlock:
      type: object
      required:
      - signature
      - key
      - algorithm
      - timestamp
      - fileHash
      - version
      properties:
        signature:
          type: string
        key:
          type: string
        algorithm:
          type: string
        timestamp:
          type: string
        fileHash:
          type: string
        version:
          type: integer
          format: int32
    CreateSignatureRequestRequest:
      type: object
      required:
      - signerUserIds
      properties:
        signerUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        message:
          type: string
        messageChannel:
          $ref: '#/components/schemas/MessageChannelConfig'
        isSequential:
          type: boolean
    ResultsSignature:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Signature'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    Geopoint:
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          type: string
          description: Type of point
          readOnly: true
        coordinates:
          type: array
          description: The longitude and latitude of the point
          readOnly: true
          items:
            type: number
            format: double
    ResultsSignatureRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SignatureRequest'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    Attribution:
      type: object
      properties:
        principalUserId:
          type: string
          example: 588f7ee98f138b19220041a7
        agentUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        eventId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiChatId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiToolUseId:
          type: string
        channel:
          type: string
          enum:
          - WEB
          - MOBILE
          - SLACK
          - TEAMS
          - MCP
    Signature:
      type: object
      required:
      - id
      - orgId
      - signatureRequestId
      - fileId
      - status
      - userId
      properties:
        id:
          type: string
          description: globally unique id of signature
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent org id
          example: 588f7ee98f138b19220041a7
        signatureRequestId:
          type: string
          description: signature request that this signature belongs to
          example: 588f7ee98f138b19220041a7
        fileId:
          type: string
          description: the file entity that contains this signature
          example: 588f7ee98f138b19220041a7
        status:
          type: string
          description: the status of this signature (either SIGNED or DECLINED)
          enum:
          - SIGNED
          - DECLINED
        comment:
          type: string
          description: comment given by the user for signing or not signing
        name:
          type: string
          description: full name of the signature
        title:
          type: string
          description: job title used in the signature
        userId:
          type: string
          description: the user who signed or declined
          example: 588f7ee98f138b19220041a7
        personId:
          type: string
          description: the personId of the user who signed or declined
          example: 588f7ee98f138b19220041a7
        email:
          type: string
          description: the email address that was used by the user who signed or declined
        at:
          type: string
          description: timestamp that the signature occurred
        userAgent:
          type: string
          description: browser user-agent used by the signing user
        remoteIp:
          type: string
          description: IP address used by the signing user
        remoteIpAddress:
          description: Geolocation of the signing user
          $ref: '#/components/schemas/Address'
        loginAt:
          type: string
          description: timestamp that the user logged in on their particular token session
        authMechanism:
          type: string
          description: mechanism that was used to authenticate the user
          enum:
          - INTERNAL
          - GENERATED
          - TOKEN
          - ESCALATION
          - PASSWORD
          - GOOGLE
          - MICROSOFT
          - ADP
          - SAML
          - UNIVERSAL_SSO
          - OAUTH_PKCE
          - LOGIN_TOKEN
        signatureBlock:
          description: details on the signing to validate the signature
          $ref: '#/components/schemas/SignatureBlock'
    Address:
      type: object
      required:
      - country
      properties:
        street1:
          type: string
          description: street address, line 1
          example: 123 Anywhere Street
          minItems: 0
          maxItems: 200
        street2:
          type: string
          description: street address, line 2
          example: Apt 6L
          minItems: 0
          maxItems: 200
        street3:
          type: string
          description: street address, line 3
          example: Sixth Floor
          minItems: 0
          maxItems: 200
        city:
          type: string
          description: city
          example: New York
          minItems: 0
          maxItems: 80
        state:
          type: string
          description: state
          example: NY
          minItems: 0
          maxItems: 80
        country:
          type: string
          description: country (two-digit ISO code)
          example: NY
          pattern: ^[A-Z]{2}$
        postal:
          type: string
          description: postal code
          example: '10001'
          minItems: 0
          maxItems: 10
        geo:
          description: geopoint location
          $ref: '#/components/schemas/Geopoint'
        approxGeo:
          description: approximate geopoint location (suitable for a map placement, but not exact location)
          $ref: '#/components/schemas/Geopoint'
    SignatureRequest:
      type: object
      required:
      - id
      - orgId
      - fileId
      - fileHash
      - fileEntityId
      - fileEntityType
      - status
      - signers
      - requestAt
      - requestUserId
      properties:
        id:
          type: string
          description: globally unique id of signature request
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent org id
          example: 588f7ee98f138b19220041a7
        fileId:
          type: string
          description: file id that is being signed
          example: 588f7ee98f138b19220041a7
        fileVersionId:
          type: string
          description: file version id that is being signed
          example: 588f7ee98f138b19220041a7
        fileHash:
          type: string
          description: SHA-256 hash of the contents of the file
        fileTemplateId:
          type: string
          description: template id that was used to generate the file, if applicable
          example: 588f7ee98f138b19220041a7
        externalId:
          type: string
          description: external id, if an external signature service is used
        externalService:
          type: string
          description: external signature service name (e.g. boldsign)
        standard:
          type: string
          description: signature standard used, defaults to SES if not specified
          enum:
          - QES
        fileEntityId:
          type: string
          description: the entity that stores the signed file
          example: 588f7ee98f138b19220041a7
        fileEntityType:
          type: string
          description: the entity that stores the signed file
          enum:
          - PERSON
          - USER
          - ORG
        status:
          type: string
          description: the overall status of this signature request
          enum:
          - PENDING
          - SIGNED
          - DECLINED
          - CANCELED
        signers:
          type: array
          description: the signers of this signature request
          items:
            $ref: '#/components/schemas/SignatureSigner'
        requestAt:
          type: string
          description: the timestamp that the request was made
        requestUserId:
          type: string
          description: the user who made the request to sign
          example: 588f7ee98f138b19220041a7
        notifyUserIds:
          type: array
          description: additional user ids to notify on signature events
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        signAt:
          type: string
          description: the timestamp that it was signed, if it was signed
        cancelAt:
          type: string
          description: the timestamp that it was canceled, if it was canceled
        declineAt:
          type: string
          description: the timestamp that it was declined, if it was declined
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
    SignatureSigner:
      type: object
      required:
      - userId
      - status
      - order
      properties:
        userId:
          type: string
          example: 588f7ee98f138b19220041a7
        status:
          type: string
          enum:
          - PENDING
          - SIGNED
          - DECLINED
          - CANCELED
        order:
          type: integer
          format: int32
    SignRequest:
      type: object
      required:
      - fileHash
      properties:
        signatureName:
          type: string
        fileHash:
          type: string
        comment:
          type: string
    ExternalSignUrlResponse:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
x-provenance:
  method: harvested
  publisher: Charthop
  source: https://api.charthop.com/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)