GoNitro Sign API
The Sign API from GoNitro — 22 operation(s) for sign.
OpenAPI Specification
openapi: 3.0.3
info:
title: Nitro PDF Services Public Authentication Sign API
description: 'REST API for Nitro PDF Services: convert, transform, extract, and generate PDF documents, plus async job status/result retrieval. Machine-to-machine OAuth 2.0 client-credentials; short-lived bearer tokens. Assembled by API Evangelist from Nitro''s published per-tool OpenAPI reference fragments; schemas preserved verbatim.'
version: '1.0'
servers:
- url: https://api.gonitro.dev
description: API server
security:
- BearerAuth: []
tags:
- name: Sign
paths:
/sign/envelopes/{envelopeID}:cancel:
put:
tags:
- Sign
summary: Cancel Envelope by ID
description: 'The **Cancel Envelope by ID** endpoint cancels the signing request for the envelope specified by its UUIDv4 identifier.
This endpoint allows you to cancel an envelope and changes its status to Cancelled but keeps it available for reference and reuse after updates. In Cancelled status, no further signing operations can be done on the envelope.
**Note:** Only envelopes that have been sent for signing can be cancelled. Draft envelopes cannot be cancelled.
'
operationId: cancelEnvelope
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Envelope cancelled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendedEnvelope'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'409':
description: Envelope cannot be modified
content:
application/problem+json:
schema:
$ref: '#/components/schemas/EnvelopeInInvalidStateProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/documents:reorder:
put:
tags:
- Sign
summary: Reorder Documents by Envelope ID
description: 'The **Reorder Documents by Envelope ID** endpoint reorders all documents associated with a specific envelope based on the order specified in the request body.
Documents are returned in an `items` array within the JSON response reflecting the new order.
'
operationId: reorderDocuments
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReorderDocumentsRequest'
required: true
responses:
'200':
description: Documents reordered successfully.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PendingDocumentResponse'
- $ref: '#/components/schemas/UploadedDocumentResponse'
- $ref: '#/components/schemas/FailedDocumentResponse'
- $ref: '#/components/schemas/SignedDocumentResponse'
- $ref: '#/components/schemas/SealedDocumentResponse'
examples:
Reordered Documents Response Example:
description: Reordered Documents Response Example
value:
items:
- ID: 987e6543-e21b-12d3-a456-426614174999
name: First Document
statue: pending
createdAt: '2023-11-07T05:31:56Z'
- ID: bc58d090-1368-4764-96b2-e59f8e4c0e0c
name: Second Document
statue: pending
createdAt: '2023-11-08T05:31:56Z'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'409':
description: Envelope cannot be modified
content:
application/problem+json:
schema:
$ref: '#/components/schemas/EnvelopeInInvalidStateProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}:send-reminders:
post:
tags:
- Sign
summary: Send Reminders for Envelope
description: 'The **Send Reminders for Envelope** endpoint triggers reminder notifications to pending participants of a specified envelope using its UUIDv4 identifier.
'
operationId: sendReminders
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendReminders'
responses:
'202':
description: Reminders triggered successfully
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'409':
description: Reminder cannot be sent
content:
application/problem+json:
schema:
$ref: '#/components/schemas/EnvelopeInInvalidStateProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}:send-for-signing:
post:
tags:
- Sign
summary: Send Envelope for Signing
description: 'The **Send Envelope for Signing** endpoint sends an envelope to participants for signature collection.
**Note**: All documents in the envelope must have an "uploaded" status before the envelope can be sent for signature.
'
operationId: sendForSigning
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Envelope successfully sent for signing
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'409':
description: Envelope is in an invalid state for sending
content:
application/problem+json:
schema:
$ref: '#/components/schemas/EnvelopeInInvalidStateProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/participants:batch-delete:
post:
tags:
- Sign
summary: Delete Participants by Participant IDs
description: The **Delete Participants** endpoint permanently deletes multiple participants from an envelope.
operationId: deleteParticipants
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteParticipantsRequest'
required: true
responses:
'200':
description: Participants deleted successfully
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/participants:
get:
tags:
- Sign
summary: List Participants by Envelope ID
description: 'The **List Participant by Envelope ID** endpoint returns all participants associated with a specific envelope.
The request must include the envelope ID to ensure the complete set of participants is retrieved for the correct envelope.
'
operationId: listParticipants
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: List participants
content:
application/json:
schema:
$ref: '#/components/schemas/ParticipantList'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
post:
tags:
- Sign
summary: Create Participant(s) by Envelope ID
description: "The **Create Participant(s) by Envelope ID** endpoint adds one or more participants to a specified envelope.\nAccepts either a single participant object or a bulk request with an 'items' array.\nParticipants are associated to the parent Envelope and can sign multiple fields in different documents.\n\nWhen creating participants, the following limits apply:\n - Maximum participants: 200\n"
operationId: createParticipant
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
description: Participant creation request - single or bulk
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SingleParticipantRequest'
- $ref: '#/components/schemas/BulkParticipantRequest'
examples:
Single Participant:
description: Create a single participant
value:
email: user@gonitro.com
role: SIGNER
authentication:
type: AccessCode
accessCode: '123456'
Bulk Participants:
description: Create multiple participants in a single request
value:
items:
- email: user@gonitro.com
role: SIGNER
authentication:
type: AccessCode
accessCode: '123456'
- email: user1@gonitro.com
role: SIGNER
authentication:
type: SMS
countryCode: '+1'
phoneNumber: '1234567890'
required: true
responses:
'201':
description: Participant created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Participant'
'200':
description: Multiple participants created successfully. Returns an object with an 'items' array containing all created participants.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkParticipantResponse'
'400':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestProblemDetail'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/documents/{documentID}/fields:batch-delete:
post:
tags:
- Sign
summary: Delete Fields by Field IDs
description: 'The **Delete Fields** endpoint permanently deletes multiple fields from a document within an envelope.
'
operationId: deleteFields
parameters:
- name: envelopeID
in: path
description: A unique string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
- name: documentID
in: path
description: A unique string that identifies the document in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteFieldsRequest'
required: true
responses:
'200':
description: Fields deleted successfully
'404':
description: Envelope or document not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/documents/{documentID}/fields:
get:
tags:
- Sign
summary: List Fields by Document ID
description: The **List Fields by Document ID** endpoint retrieves all fields associated with a specific document within an envelope. The request must include the envelope and document ID to ensure the complete set of fields is retrieved for the correct document.
operationId: listFields
parameters:
- name: envelopeID
in: path
description: A unique string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
- name: documentID
in: path
description: A unique string that identifies the document in the Nitro system.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: List of all fields. Each field contains its unique ID and configuration.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Checkbox'
- $ref: '#/components/schemas/Company'
- $ref: '#/components/schemas/Custom'
- $ref: '#/components/schemas/Date'
- $ref: '#/components/schemas/Initials'
- $ref: '#/components/schemas/Name'
- $ref: '#/components/schemas/Signature'
- $ref: '#/components/schemas/Title'
examples:
List Fields Response Example:
description: List Fields Response Example
value:
items:
- fieldID: 987e6543-e21b-12d3-a456-426614174999
participantID: 123e4567-e89b-12d3-a456-426614174000
documentID: 456e7890-e12b-34d5-a678-426614175000
page: 1
boundingBox:
- 100.0
- 200.0
- 150.0
- 50.0
required: true
type: signature
'404':
description: Envelope or document not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
post:
tags:
- Sign
summary: Create Field(s) by Document ID
description: 'The **Create Field(s) by Document ID** endpoint creates one or more fields on a document and assigns it to a participant.
Accepts either a single field object or a bulk request with an ''items'' array containing multiple field objects.
'
operationId: createField
parameters:
- name: envelopeID
in: path
description: A unique string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
- name: documentID
in: path
description: A unique string that identifies the document in the Nitro system.
required: true
schema:
type: string
format: uuid
requestBody:
description: 'Field creation request. Can be a single field object or bulk with ''items'' array.
The `type` field determines which properties are required:
- `checkbox` - Checkbox field
- `company` - Company field
- `custom` - Custom text field
- `date` - Date field
- `initials` - Initials field
- `name` - Name field
- `signature` - Signature field
- `title` - Title field
'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateCheckboxField'
- $ref: '#/components/schemas/CreateCompanyField'
- $ref: '#/components/schemas/CreateCustomField'
- $ref: '#/components/schemas/CreateDateField'
- $ref: '#/components/schemas/CreateInitialsField'
- $ref: '#/components/schemas/CreateNameField'
- $ref: '#/components/schemas/CreateSignatureField'
- $ref: '#/components/schemas/CreateTitleField'
- $ref: '#/components/schemas/BulkFieldRequest'
examples:
Single Field:
description: Single Field
value:
participantID: 3fa85f64-5717-4562-b3fc-2c963f66afa6
page: 1
boundingBox:
- 100.0
- 200.0
- 150.0
- 250.0
required: true
type: signature
Bulk Fields:
description: Bulk Fields
value:
items:
- participantID: 3fa85f64-5717-4562-b3fc-2c963f66afa6
page: 1
boundingBox:
- 100.0
- 200.0
- 150.0
- 250.0
required: true
type: signature
- participantID: 3fa85f64-5717-4562-b3fc-2c963f66afa6
page: 1
boundingBox:
- 200.0
- 300.0
- 150.0
- 50.0
required: false
type: date
format: MM/DD/YYYY
modifiable: true
required: true
responses:
'201':
description: Single Field created successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateCheckboxFieldResponse'
- $ref: '#/components/schemas/CreateCompanyFieldResponse'
- $ref: '#/components/schemas/CreateCustomFieldResponse'
- $ref: '#/components/schemas/CreateDateFieldResponse'
- $ref: '#/components/schemas/CreateInitialsFieldResponse'
- $ref: '#/components/schemas/CreateNameFieldResponse'
- $ref: '#/components/schemas/CreateSignatureFieldResponse'
- $ref: '#/components/schemas/CreateTitleFieldResponse'
example:
ID: 987e6543-e21b-12d3-a456-426614174999
participantID: 123e4567-e89b-12d3-a456-426614174000
documentID: 456e7890-e12b-34d5-a678-426614175000
page: 1
boundingBox:
- 100.0
- 200.0
- 150.0
- 250.0
required: true
type: signature
'200':
description: Fields created successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateCheckboxFieldResponse'
- $ref: '#/components/schemas/CreateCompanyFieldResponse'
- $ref: '#/components/schemas/CreateCustomFieldResponse'
- $ref: '#/components/schemas/CreateDateFieldResponse'
- $ref: '#/components/schemas/CreateInitialsFieldResponse'
- $ref: '#/components/schemas/CreateNameFieldResponse'
- $ref: '#/components/schemas/CreateSignatureFieldResponse'
- $ref: '#/components/schemas/CreateTitleFieldResponse'
example:
items:
- ID: 987e6543-e21b-12d3-a456-426614174999
participantID: 123e4567-e89b-12d3-a456-426614174000
documentID: 456e7890-e12b-34d5-a678-426614175000
page: 1
boundingBox:
- 100.0
- 200.0
- 150.0
- 250.0
required: true
type: signature
- ID: 654e3210-e21b-12d3-a456-426614174888
participantID: 123e4567-e89b-12d3-a456-426614174000
documentID: 456e7890-e12b-34d5-a678-426614175000
page: 1
boundingBox:
- 200.0
- 300.0
- 150.0
- 50.0
required: false
type: date
format: MM/DD/YYYY
modifiable: true
'400':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestProblemDetail'
'404':
description: Envelope or document not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'422':
description: The requested participant does not exist on the given package
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnprocessableEntityProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
/sign/envelopes/{envelopeID}/documents:
get:
tags:
- Sign
summary: List Documents by Envelope ID
description: 'The **List Documents by Envelope ID** endpoint retrieves all documents associated with a specific envelope. Documents are returned in an `items` array within the JSON response.
The request must include the envelope ID to ensure the complete set of documents is retrieved for the correct envelope.
'
operationId: listDocuments
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: List all documents associated with the envelope.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PendingDocumentResponse'
- $ref: '#/components/schemas/UploadedDocumentResponse'
- $ref: '#/components/schemas/FailedDocumentResponse'
- $ref: '#/components/schemas/SignedDocumentResponse'
- $ref: '#/components/schemas/SealedDocumentResponse'
examples:
List Documents Response Example:
description: List Documents Response Example
value:
items:
- ID: 987e6543-e21b-12d3-a456-426614174999
name: Document
statue: pending
createdAt: '2023-11-07T05:31:56Z'
'404':
description: Envelope not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundProblemDetail'
'401':
description: Unauthorized - Invalid or missing JWT token
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedProblemDetail'
post:
tags:
- Sign
summary: Create Document by Envelope ID
description: "In Nitro, a *Document* is a file that participants in an eSignature Envelope will read and sign. This could be an employment contract, NDA, legal agreement, banking form, or any other file required in your signature workflow.\n\nThe **Create Document by Envelope ID** endpoint supports uploading a **single** file per request.\nEvery document must be part of an Envelope container. To upload a document, first [Create an Envelope](https://developers.gonitro.com/docs/api-reference/envelope/create-envelope) and retain the Envelope `ID`.\n\n### Supported file formats\nWhen a `contentType` is provided in the metadata, the following formats are accepted and will be converted to PDF automatically:\n\n#### Document formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |\n| .doc | application/msword |\n| .dot | application/msword |\n| .docm | application/vnd.ms-word.document.macroenabled.12 |\n| .dotx | application/vnd.openxmlformats-officedocument.wordprocessingml.template |\n| .dotm | application/vnd.ms-word.template.macroenabled.12 |\n\n#### Spreadsheet formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |\n| .xls | application/vnd.ms-excel |\n| .xlt | application/vnd.ms-excel |\n| .xlsm | application/vnd.ms-excel.sheet.macroenabled.12 |\n| .xltx | application/vnd.openxmlformats-officedocument.spreadsheetml.template |\n| .xltm | application/vnd.ms-excel.template.macroenabled.12 |\n\n#### Presentation formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |\n| .ppt | application/vnd.ms-powerpoint |\n\n#### Web formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .html | text/html |\n| .htm | text/html |\n| .rtf | application/rtf |\n| .xml | application/xml |\n\n#### Image formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .png | image/png |\n| .jpg | image/jpeg |\n| .jpeg | image/jpeg |\n| .tif | image/tiff |\n| .tiff | image/tiff |\n| .gif | image/gif |\n| .psd | image/vnd.adobe.photoshop |\n| .eps | application/postscript |\n| .svg | image/svg+xml |\n\n#### Other formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .csv | text/csv |\n\n#### PDF formats\n\n| Extension | Content Type |\n|-----------|-------------|\n| .pdf | application/pdf |\n\nWhen `contentType` is omitted from the metadata, only PDF files are accepted.\n\nWhen uploading a document, the following limits apply:\n - Maximum pages per document: 250\n - Maximum size per document: 20Mb\n - Maximum documents per envelope: 15\n - Maximum size per envelope: 300 Mb\n"
operationId: createDocument
parameters:
- name: envelopeID
in: path
description: A unique UUIDv4 string that identifies the envelope in the Nitro system.
required: true
schema:
type: string
format: uuid
- name: nitroDocumentID
in: query
description: " An ID reference to a user-associated Nitro Document. Instead of uploading a new file, you can attach an existing Nitro Document to an envelope by referencing its `nitroDocumentID`. This lets you reuse documents that have already been uploaded.\n\n To do this, provide the `nitroDocumentID` **instead** of a file in the `payload`.\n\n Important: `nitroDocumentID` and `payload` parameters are mutually exclusive. You must choose one of the following combinations:\n\n `payload` + `metadata`\n\n `nitroDocumentID` + `metadata`\n\n Providing both in the same request will throw an error.\n"
required: false
schema:
type: string
description: " An ID reference to a user-associated Nitro Document. Instead of uploading a new file, you can attach an existing Nitro Document to an envelope by referencing its `nitroDocumentID`. This lets you reuse documents that have already been uploaded.\n\n To do this, provide the `nitroDocumentID` **instead** of a file in the `payload`.\n\n Important: `nitroDocumentID` and `payload` parameters are mutually exclusive. You must choose one of the following combinations:\n\n `payload` + `metadata`\n\n `nitroDocumentID` + `metadata`\n\n Providing both in the same request will throw an error.\n"
minimum: 0
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
metadata:
$ref: '#/components/schemas/EnvelopeWebDocumentRequestMetadata'
description: The Metadata for the uploaded document
payload:
type: string
format: binary
description: "The document to upload, provided as binary data. Each file can be up to 20 MB and 250 pages.\n\nAn Envelope can include up to 15 files total, with a combined size limit of 300 MB.\n\nExample:\n```bash\n curl -X POST \"https://api.gonitro.dev/sign/envelopes/{envelopeID}/documents\" -H \"Authorization: Bearer <token>\" -F 'metadata={\"name\":\"<your_document_name>\",\"contentType\":\"application/pdf\"};type=application/json' -F \"payload=@/path/to/document.pdf\" # @ symbol reads file content\n ```\n"
required:
- metadata
encoding:
metadata:
contentType: application/json
payload:
contentType: application/octet-stream
nitroDo
# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gonitro/refs/heads/main/openapi/gonitro-sign-api-openapi.yml