Documents

Managing Documents

When you create a new Transaction, you are required to include at least one Document, one Participant, and one Task per Document/Participant. However, after the Transaction is created, you can add new Documents or update existing Documents via the API at any point as long as the transaction is still in the Pending status.

Insert a Document

In order to insert a new Document into an existing Transaction, you'll need provide Transaction ID along with the new Document's details. At least one Task is required in the newly inserted Document, as well.

var req = new DocumentInsertRequestModel() {
    Documents = new List<object> {
        new DocumentInsertModel() {
            TransactionID = 1234567890,
                Title = "Web Services Insert Test Document",
                Source = new SourceModel() {
                    FilePath = @ "c:\myDocument.pdf"
                },
                Tasks = new List<object> {
                    new TaskInsertModel() {
                        ParticipantID = 1987654320
                    }
                }
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.InsertDocuments(req, apiKey, apiSecret, apiUsername, apiPassword);;
if (results.IsSuccessful.Value) {
    //do work...
} else {
    //handle error
}

Update a Document

In order to update an existing Document, you'll need to retrieve an existing "Updateable" Document first. Once you have the DocumentUpdateModel you can add/update/delete any properties you wish from that object and then all the UpdateDocuments() method to commit the update.

var req = new DocumentUpdateableRequestModel() {
    IDs = new List<object> {
        1234567890
    }
};

var api = new DocumentsUpdateableApi(myRestEndpointUrl);
var results = api.GetDocumentsUpdateable(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value) {
    results.UpdateableDocuments[0].Title = "UPDATED!";
    var updateModel = new DocumentUpdateRequestModel() {
        Documents = results.UpdateableDocuments
    };

    var api = new DocumentsApi(myRestEndpointUrl);
    var updateResults = api.UpdateDocuments(req, apiKey, apiSecret, apiUsername, apiPassword);
    if (updateResults.IsSuccessful) {
        //do work...
    } else {
        //handle error
    }
} else {
    //handle error
}

Update a Completed Document

var req = new DocumentCompletedUpdateableRequestModel()
            {
                IDs = new List<object> { 1234567890 }
            };

var api = new DocumentsUpdateableApi(myRestEndpointUrl);
var results = api.GetDocumentsCompletedUpdateable(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
    results.UpdateableDocuments[0].Title = "UPDATED!";
    var updateModel = new DocumentCompletedUpdateRequestModel()
                      {
                          Documents = results.UpdateableDocuments
                      };

    var api = new DocumentsUpdateableApi(myRestEndpointUrl);
    var updateResults = api.UpdateDocumentsCompleted(req, apiKey, apiSecret, apiUsername, apiPassword);
    if (updateResults.IsSuccessful)
    {
        //do work...
    }
    else
    {
        //handle error
    }
}
else
{
    //handle error
}

Update Form Fields

var req = new DocumentUpdateFormFieldsRequestModel() {
    DocumentFormFields = new List<object> {
        new DocumentFormFieldsModel() {
            DocumentID = 1000435535,
                FormFields = new FList<object> {
                    new FormFieldModel() {
                            Name = "City",
                                Value = "Dallas"
                        },
                        new FormFieldModel() {
                            Name = "State",
                                Value = "TX"
                        }
                }
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.UpdateDocumentFormFields(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value) {
    //do work...
} else {
    //handle error
}

Stamp Text in a Document

var req = new DocumentUpdateTextStampsRequestModel() {
    DocumentTextStamps = new List<object> {
        new DocumentTextStampsModel() {
            DocumentID = 1234567890,
                TextStamps = new List<object> {
                    new TextStampModel() {
                            TextToStamp = "THIS IS A TEST",
                                FontColor = TextStampModel.FontColorEnum.Black,
                                FontSize = 10,
                                PageCoordinatesPageNumber = 1,
                                XOffset = 50,
                                YOffset = 50
                        },
                        new TextStampModel() {
                            TextToStamp = "Another test!",
                                FontColor = TextStampModel.FontColorEnum.Blue,
                                FontSize = 8,
                                SearchTextText = "{{MyPlaceHolderText}}",
                                SearchTextStartPosition = TextStampModel.SearchTextStartPositionEnum.Bottom
                        },
                        new TextStampModel() {
                            TextToStamp = "Yes Another test!",
                                FontColor = TextStampModel.FontColorEnum.Red,
                                FontSize = 8,
                                SearchTextText = "{{MyPlaceHolderText}}",
                                SearchTextStartPosition = TextStampModel.SearchTextStartPositionEnum.Top,
                                SearchTextInstance = 2
                        },
                        new TextStampModel() {
                            TextToStamp = "FORM FIELD PLACEMENT",
                                FontColor = TextStampModel.FontColorEnum.Red,
                                FontSize = 8,
                                FormFieldFieldName = "Date",
                                XOffset = 20,
                                YOffset = 20
                        }
                }
        }
    }
};
var result = serviceClient.UpdateDocumentTextStamps(req, apiKey, apiSecret, apiUsername, apiPassword);
if (result.IsSuccessful) {
    // do work
} else {
    // handle error
}

The GetDocumentFileLinks() method generates secure, time-limited download links for documents within a transaction. This method provides flexible access to documents by allowing you to specify different ID types to control which documents are included in the response.

Access Patterns

You can use any of the following IDs to access documents:

  • TransactionID: Returns all documents in the transaction combined into a single PDF or HTML viewer
  • DocumentID: Returns only the specified document
  • ParticipantID: Returns only the documents that the specified participant was involved in for the transaction (subset of transaction documents)

Response Format

The returned link will provide access to either:

  • Single PDF: All requested documents combined into one downloadable PDF file
  • HTML Viewer: An HTML page displaying each document with a selection box to switch between documents

Method Signature

public DocumentFileLinksResponseModel GetDocumentFileLinks(
    DocumentFileLinksRequestModel request,
    string apiKey,
    string apiSecret,
    string apiUsername,
    string apiPassword
)

Request Model

DocumentFileLinksRequestModel

PropertyTypeDescription
LinkRequestsList<DocumentFileLinkRequestModel>Collection of link request objects

DocumentFileLinkRequestModel

PropertyTypeRequiredDescription
TransactionIDlong?Conditional*ID of the transaction containing the documents
DocumentIDlong?Conditional*ID of a specific document to retrieve
ParticipantIDlong?Conditional*ID of participant to filter documents by their involvement
ExpiresInSecondsintYesNumber of seconds until the link expires (e.g., 11300 for ~3 hours)
DownloadFileNamestringNoCustom filename for the downloaded file (e.g., "MyTestFile.pdf")
DisplayPdfAsHtmlFormatboolNoIf true, displays documents in HTML viewer; if false, provides direct PDF download

*At least one ID (TransactionID, DocumentID, or ParticipantID) must be provided.

Response Model

DocumentFileLinksResponseModel

PropertyTypeDescription
IsSuccessfulboolIndicates if the request was processed successfully
MessagestringError message if IsSuccessful is false, otherwise null
DocumentFileLinksList<DocumentFileLinkModel>Collection of generated file links
ProcessingTimeTimeSpanTime taken to process the request
TimeZoneUtcOffsetdoubleUTC offset for timestamp calculations

DocumentFileLinkModel

PropertyTypeDescription
UrlstringThe secure download/view URL for the document(s)

Code Examples

Get All Documents in a Transaction

var req = new DocumentFileLinksRequestModel()
{
    LinkRequests = new List<DocumentFileLinkRequestModel>
    {
        new DocumentFileLinkRequestModel()
        {
            TransactionID = 1000242814,
            ExpiresInSeconds = 11300,
            DownloadFileName = "TransactionDocuments.pdf",
            DisplayPdfAsHtmlFormat = false
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.GetDocumentFileLinks(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
    string downloadUrl = results.DocumentFileLinks[0].Url;
    // Use the download URL to provide access to the document(s)
    // do work...
}
else
{
    //handle error
    string errorMessage = results.Message;
}

Get a Specific Document

var req = new DocumentFileLinksRequestModel()
{
    LinkRequests = new List<DocumentFileLinkRequestModel>
    {
        new DocumentFileLinkRequestModel()
        {
            DocumentID = 1234567890,
            ExpiresInSeconds = 7200, // 2 hours
            DownloadFileName = "SpecificDocument.pdf",
            DisplayPdfAsHtmlFormat = false
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.GetDocumentFileLinks(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
    string downloadUrl = results.DocumentFileLinks[0].Url;
    // do work...
}
else
{
    //handle error
}

Get Documents for a Specific Participant with HTML Viewer

var req = new DocumentFileLinksRequestModel()
{
    LinkRequests = new List<DocumentFileLinkRequestModel>
    {
        new DocumentFileLinkRequestModel()
        {
            ParticipantID = 1987654321,
            ExpiresInSeconds = 3600, // 1 hour
            DisplayPdfAsHtmlFormat = true // Display in HTML viewer
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.GetDocumentFileLinks(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
    string viewerUrl = results.DocumentFileLinks[0].Url;
    // Redirect user to the HTML viewer URL
    // do work...
}
else
{
    //handle error
}
var req = new DocumentFileLinksRequestModel()
{
    LinkRequests = new List<DocumentFileLinkRequestModel>
    {
        new DocumentFileLinkRequestModel()
        {
            TransactionID = 1000242814,
            ExpiresInSeconds = 11300,
            DownloadFileName = "AllDocuments.pdf",
            DisplayPdfAsHtmlFormat = false
        },
        new DocumentFileLinkRequestModel()
        {
            DocumentID = 1234567890,
            ExpiresInSeconds = 7200,
            DownloadFileName = "SingleDocument.pdf",
            DisplayPdfAsHtmlFormat = false
        }
    }
};

var api = new DocumentsApi(myRestEndpointUrl);
var results = api.GetDocumentFileLinks(req, apiKey, apiSecret, apiUsername, apiPassword);
if (results.IsSuccessful.Value)
{
    foreach (var link in results.DocumentFileLinks)
    {
        string downloadUrl = link.Url;
        // Process each link
    }
    // do work...
}
else
{
    //handle error
}

Example Response JSON

{
    "IsSuccessful": true,
    "Message": null,
    "DocumentFileLinks": [
        {
            "Url": "https://q1.alphatrust.com/SignApi/api/DocumentLinks/f61a5847b8d0443b/inline"
        }
    ],
    "ProcessingTime": "00:00:00.7079863",
    "TimeZoneUtcOffset": 0.0
}

Important Notes

  • Security: Generated links are time-limited and expire based on the ExpiresInSeconds parameter
  • File Format: When DisplayPdfAsHtmlFormat is false, documents are combined into a single PDF for download
  • HTML Viewer: When DisplayPdfAsHtmlFormat is true, an interactive HTML page is provided with document navigation
  • Multiple Documents: Multiple link requests can be processed in a single API call
  • Custom Filenames: Use DownloadFileName to specify a custom name for downloaded files
  • Access Control: Different ID types (Transaction, Document, Participant) provide different levels of document access