AnnotationsApi
All URIs are relative to https://api.esignlaunchpad.com
| Method | HTTP request | Description |
|---|---|---|
| applyDetectedTags | POST /api/v1/packages//apply-detected-tags | Apply detected text tags as annotations |
| createAnnotation | POST /api/v1/packages//annotations | Create an annotation |
| createAnnotationsBulk | POST /api/v1/packages//annotations/bulk | Create annotations in bulk |
| deleteAnnotation | DELETE /api/v1/packages//annotations/ | Delete an annotation |
| getAnnotation | GET /api/v1/packages//annotations/ | Get an annotation by ID |
| listAnnotations | GET /api/v1/packages//annotations | List annotations in a package |
| updateAnnotation | PUT /api/v1/packages//annotations/ | Update an annotation |
| validateAnnotations | POST /api/v1/packages//annotations/validate | Validate annotations for sending |
applyDetectedTags
BulkAnnotationApiResponse applyDetectedTags(packageId)
Apply detected text tags as annotations
Scans all documents in the package for previously detected text tags (e.g., {{sig_1}}, {{initial_2}}) and creates corresponding annotations at the tag locations. Text tags are detected during document upload/processing and stored as metadata on each document. This operation is idempotent: documents that already have annotations are skipped entirely. It will not duplicate annotations on a document that has already been processed. Documents with no detected tags produce no annotations. Use the Documents API's tag detection endpoint to preview which tags were found before calling this endpoint. The package must be in Draft status.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package whose documents should have tags converted to annotations. | [default to null] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
createAnnotation
AnnotationApiResponse createAnnotation(packageId, CreateAnnotationApiRequest)
Create an annotation
Creates a single annotation such as a signature, initials, date, text, checkbox, or dropdown field at the specified position on a document page. The annotation is assigned to a signer by their zero-based index in the package's signer list. The package must be in Draft status. Attempting to add annotations to a sent or completed package will fail. The referenced document must belong to the specified package. Position (X, Y) and dimensions (Width, Height) are in PDF points (1pt = 1/72 inch). A US Letter page is 612 wide x 792 tall; A4 is 595 x 842. Origin is the top-left of the page: X grows right, Y grows down. If you omit Width and Height, the server applies type-aware defaults scaled to the document's body-text size, which is the recommended approach unless you have a specific layout in mind. Server-side per-type minimums are always enforced (e.g., a Signature is never rendered below ~120x30pt) so values that are too small are clamped up rather than rejected. For Checkbox annotations, MustBeChecked controls whether the signer is forced to check the box (defaults to true). For Dropdown and RadioGroup annotations, the Options list must be provided. For anchor-based placement, provide AnchorText to auto-position relative to text found in the document.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package containing the target document. | [default to null] |
| CreateAnnotationApiRequest | CreateAnnotationApiRequest | Cancellation token. |
Return type
Authorization
HTTP request headers
- Content-Type: application/json, text/json, application/*+json
- Accept: application/json
createAnnotationsBulk
BulkAnnotationApiResponse createAnnotationsBulk(packageId, BulkCreateAnnotationApiRequest)
Create annotations in bulk
Use this endpoint to efficiently place many fields at once rather than issuing individual create requests. Annotations are grouped by document internally and created in batch per document. All annotations in the request must reference documents that belong to the specified package. This is an all-or-nothing operation per document group: if any annotation in a document group fails validation (e.g., invalid type), the entire request fails. The package must be in Draft status. Each item in the Annotations array follows the same schema and validation rules as the single-create endpoint. See Task<IActionResult> AnnotationsController.CreateAnnotation(Guid packageId, CreateAnnotationApiRequest request, CancellationToken ct) for field details.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package containing the target documents. | [default to null] |
| BulkCreateAnnotationApiRequest | BulkCreateAnnotationApiRequest | Cancellation token. |
Return type
Authorization
HTTP request headers
- Content-Type: application/json, text/json, application/*+json
- Accept: application/json
deleteAnnotation
deleteAnnotation(packageId, annotationId)
Delete an annotation
Deletes the annotation identified by its GUID. The package must be in Draft status. Once deleted, the annotation GUID cannot be reused. If the annotation was the only annotation assigned to a particular signer on a document, the signer will have no fields to complete on that document. This operation is idempotent in terms of the final state, but returns 404 if the annotation does not exist.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package containing the annotation. | [default to null] |
| annotationId | UUID | GUID of the annotation to delete. | [default to null] |
Return type
null (empty response body)
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
getAnnotation
AnnotationApiResponse getAnnotation(packageId, annotationId)
Get an annotation by ID
Returns the full annotation details including its current completion state. The annotation must belong to a document within the specified package, and the package must belong to the authenticated tenant.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package containing the annotation. | [default to null] |
| annotationId | UUID | GUID of the annotation to retrieve. | [default to null] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
listAnnotations
List listAnnotations(packageId, documentId)
List annotations in a package
Without the documentId query parameter, returns all annotations across every document in the package. When documentId is provided, returns only annotations belonging to that specific document. Each annotation in the response includes its completion status. During an active signing ceremony, IsCompleted, CompletedValue, and CompletedOn reflect real-time signer progress.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package to list annotations for. | [default to null] |
| documentId | UUID | Optional. When provided, filters results to only annotations on this document. | [optional] [default to null] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
updateAnnotation
AnnotationApiResponse updateAnnotation(packageId, annotationId, UpdateAnnotationApiRequest)
Update an annotation
This is a partial update (PATCH semantics via PUT): only non-null fields in the request body are applied. Omitted or null fields retain their current values. For example, to reposition an annotation without changing its signer assignment, send only X, Y, PageNumber. The package must be in Draft status. The annotation type cannot be changed after creation; delete and recreate the annotation if a different type is needed.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package containing the annotation. | [default to null] |
| annotationId | UUID | GUID of the annotation to update. | [default to null] |
| UpdateAnnotationApiRequest | UpdateAnnotationApiRequest | Cancellation token. |
Return type
Authorization
HTTP request headers
- Content-Type: application/json, text/json, application/*+json
- Accept: application/json
validateAnnotations
AnnotationValidationApiResponse validateAnnotations(packageId)
Validate annotations for sending
Runs validation rules across all annotations in every document of the package. Typical checks include: required annotations must be assigned to valid signers, dropdown/radio annotations must have options defined, signer indices must reference existing signers, and annotations must be positioned within page bounds. Call this before sending a package to catch configuration errors early. The response includes IsValid (true if no errors) and a detailed list of errors, each referencing the specific document and annotation that failed. This is a read-only operation that does not modify the package. It can be called at any stage, not just on Draft packages.
Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| packageId | UUID | GUID of the package to validate. | [default to null] |
Return type
AnnotationValidationApiResponse
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json