Charthop signature-request API
The signature-request API from Charthop — 9 operation(s) for signature-request.
OpenAPI Specification
swagger: '2.0'
info:
description: REST API for ChartHop
version: V1.0.0
title: ChartHop access signature-request API
contact:
name: ChartHop
url: https://www.charthop.com
email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: signature-request
paths:
/v1/org/{orgId}/signature-request:
get:
tags:
- signature-request
summary: Return signature requests
operationId: findSignatureRequests
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: requestUserId
in: query
description: Filter by signature requests requested by an individual
required: false
type: string
- name: signUserId
in: query
description: Filter by signature requests requested for signature of an individual
required: false
type: string
- name: fromCreateAt
in: query
description: Filter by signature requests requested from a particular timestamp
required: false
type: string
- name: untilCreateAt
in: query
description: Filter by signature requests requested up until a particular timestamp
required: false
type: string
- name: from
in: query
description: Signature request id to start from, when paginating
required: false
type: string
- name: limit
in: query
description: Number of results to return
required: false
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
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: fileId
in: path
description: File identifier
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: fileId
in: path
description: File identifier
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/CreateSignatureRequestRequest'
responses:
'400':
description: bad request
'401':
description: not authorized
'404':
description: not found
/v1/org/{orgId}/signature-request/usage:
get:
tags:
- signature-request
summary: Retrieve current signature request usage for the organization
operationId: getSignatureRequestUsage
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: Filter by signature requests requested by an individual
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: The signature request id to cancel
required: true
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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: The signature request id to decline
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/SignRequest'
responses:
'400':
description: bad request
'401':
description: not authorized
'404':
description: not found
/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 service
operationId: getSignatureRequestExternalUrl
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: Signature request ID
required: true
type: string
- name: redirectPath
in: query
description: Redirect path to send user to when signature is complete
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/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
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: The signature request id to sign
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/SignRequest'
responses:
'400':
description: bad request
'401':
description: not authorized
'404':
description: not found
/v1/org/{orgId}/signature-request/{id}/signature:
get:
tags:
- signature-request
summary: Retrieve all of the signatures relating to a signature request
operationId: findSignaturesOnSignatureRequest
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: id
in: path
description: Filter by signature requests requested by an individual
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/ResultsSignature'
'400':
description: bad request
'401':
description: not authorized
'404':
description: not found
definitions:
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
ResultsAccess:
type: object
required:
- allowed
properties:
ids:
type: array
uniqueItems: true
items:
type: string
example: 588f7ee98f138b19220041a7
allowed:
type: array
uniqueItems: true
items:
$ref: '#/definitions/AccessAction'
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
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: '#/definitions/Geopoint'
approxGeo:
description: approximate geopoint location (suitable for a map placement, but not exact location)
$ref: '#/definitions/Geopoint'
CreateSignatureRequestRequest:
type: object
required:
- signerUserIds
properties:
signerUserIds:
type: array
items:
type: string
example: 588f7ee98f138b19220041a7
message:
type: string
messageChannel:
$ref: '#/definitions/MessageChannelConfig'
isSequential:
type: boolean
ExternalSignUrlResponse:
type: object
required:
- url
properties:
url:
type: string
format: uri
ResultsSignature:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/Signature'
next:
type: string
access:
type: array
items:
$ref: '#/definitions/ResultsAccess'
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: '#/definitions/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: '#/definitions/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: '#/definitions/Attribution'
updateAt:
type: string
description: last updated timestamp
example: '2017-01-24T13:57:52Z'
SignRequest:
type: object
required:
- fileHash
properties:
signatureName:
type: string
fileHash:
type: string
comment:
type: string
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
MessageChannelConfig:
type: object
required:
- channels
- alwaysEmail
properties:
channels:
type: array
items:
type: string
enum:
- EMAIL
- CHAT
- CHAT_SLACK
- CHAT_TEAMS
alwaysEmail:
type: boolean
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
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
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
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: '#/definitions/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: '#/definitions/SignatureBlock'
ResultsSignatureRequest:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/SignatureRequest'
next:
type: string
access:
type: array
items:
$ref: '#/definitions/ResultsAccess'