Creating a Simple Transaction

When creating a transaction (i.e. getting a document signed), there are four main objects that need to be defined: the Transaction, the Participant, the Document, and the Task.

What You'll Learn

This guide walks you through creating your first e-signature transaction. You'll learn how to:

• Configure a transaction with participants and documents
• Set up signature tasks and placement on PDFs
• Make authenticated API calls to create transactions
• Handle successful responses and errors

Understanding Object Relationships

The four main objects work together in a specific way:

• Transaction - The container for the entire signing workflow
• Participant - The person who will sign (one or more per transaction)
• Document - The PDF file to be signed (one or more per transaction)
• Task - The action to perform (e.g., signature, initial, text field)

Key Concept: When you assign a Task to both a Document and a Participant, you're creating a relationship that says "this participant must perform this task on this document." This is how the system knows who signs what and where.

Transaction

The first step would be to set up the Transaction which is done through the TransactionCreateModel.

var t = new TransactionCreateModel();
t.IsTest = true;
t.Description = "My First Transaction Test";
t.ProntoID = "Default";

Participant

Next we'll need to define and add in the Participant to the Transaction using the ParticipantInsertModel.

var participant = new ParticipantInsertModel();
participant.FullName = "John Smith";
participant.EmailAddress = "testing@alphatrust.com";
// SendRequestViaEmail=true will automatically email the signing request to this participant
participant.SendRequestViaEmail = true;

// Add the participant to the transaction (supports multiple participants in the array)
t.Participants = new List<object> { participant };

Document

Next we'll need to define and add in the Document to the Transaction using the DocumentInsertModel.

var document = new DocumentInsertModel();
document.Title = "My Test Document";

var src = new SourceModel();
// Load the PDF file as a byte array - this must be a valid PDF file
src.FileBytes = System.IO.File.ReadAllBytes(@"C:\MyDocument.pdf");

document.Source = src;

// Add the document to the transaction (supports multiple documents in the array)
t.Documents = new List<object> { document };

Task

Next we'll need to define the Task using the TaskInsertModel along with the SignatureBlockModel, the SignatureModel, and the PdfSignaturePlacementModel. The latter three are optional for refined signature placement and configurations. However, it is highly recommended that you use these additional configurations for most scenarios.

// Initialize all of the necessary Task objects
var task = new TaskInsertModel();
var sigBlock = new SignatureBlockModel();
var sig = new SignatureModel();
var placement = new PdfSignaturePlacementModel();

// Set the task type to Signature (other options: Initial, Text, Checkbox, etc.)
task.Type = TaskInsertModel.TypeEnum.Signature;

// Configure how the signature appears: FontStamped uses the participant's typed name
// in a font-based signature (other options: Handwritten, Image)
sig.ApplicationType = SignatureModel.ApplicationTypeEnum.FontStamped;
sig.IsBold = true;
sig.IsItalic = true;

// Set the signature location on the PDF (page 1, 20 points from left, 20 points from top)
placement.PageCoordinatesPageNumber = 1;
placement.XOffset = 20;
placement.YOffset = 20;

// Build the task hierarchy: placement → signature → signature block → task
sig.PdfPlacement = placement;
sigBlock.Signature = sig;
task.SignatureBlock = sigBlock;

// CRITICAL: Assign the task to BOTH the document AND the participant
// This creates the relationship: "John Smith must sign this signature field on My Test Document"
document.Tasks = new List<object> { task };
participant.Tasks = new List<object> { task };

Finalizing the Service Request

As described here in more detail, all service methods require the Service Authentication values to be included.

var apiKey = "MyCompanyInc";
var apiSecret = "4dda426f-134f-4a55-9dff-40f4c227e1a0";
var apiUsername = "my-api-user";
var apiPassword = "17334bae-5eff-4ee1-9a96-fa5dde6cbfc9";

Most service methods allow an array of objects to be passed in which enables you, in this instance, to create multiple transactions with one call. In this demo, we will just be creating one transaction. However, we will still need to pass that one transaction into an array before we pass it into the service method.

var transactionList = new List<object> { t };

Now that we have all of the required objects defined, we just need to wrap them up in the request object. When creating new transactions, that request object is the TransactionCreateRequestModel. This request object allows you to include additional features to be include with the request and the response that are outside the Transaction object's responsibility. The properties are EnableLogging and the ResponseIncludes. The latter property will allow fine-grained control as to what gets returned in the response to the service call using, in this scenario, the TransactionIncludesModel.

var req = new TransactionCreateRequestModel();
req.EnableLogging = true;
req.Transactions = transactionList;

// Optional: Specify what additional data to include in the response
// This is useful for getting signing URLs, IDs, and other properties you'll need
var includes = new TransactionIncludesModel();
includes.ParticipantSigningUrl = true;  // Get the URL to send participants for signing
includes.DocumentId = true;              // Get the unique document identifier
includes.ParticipantId = true;           // Get the unique participant identifier
req.ResponseIncludes = includes;

Include these properties in the CreateTransactions() service method and handle the results as detailed in the Default Service Return Properties section.

var myRestEndpointUrl = "https://my-esign-domain.com/rest";
var api = new TransactionsApi(myRestEndpointUrl);
var results = await api.CreateTransactionsAsync(req, apiKey, apiSecret, apiUsername, apiPassword);

if (results.IsSuccessful.Value)
{
    // Transaction created successfully!
    // Access transaction details from results.Transactions[0]
    var transactionId = results.Transactions[0].TransactionID;
    var signingUrl = results.Transactions[0].Participants[0].SigningUrl;

    // Send the signing URL to your participant or redirect them to it
    Console.WriteLine($"Transaction created: {transactionId}");
    Console.WriteLine($"Signing URL: {signingUrl}");
}
else
{
    // Handle error - the Message property will contain details about what went wrong
    Console.WriteLine($"Error creating transaction: {results.Message}");
}

Putting it all together

Now that we've described each piece in detail, below is the full source code for the example.

var t = new TransactionCreateModel();
t.IsTest = true;
t.Description = "My First Transaction Test";
t.ProntoID = "Default";

var participant = new ParticipantInsertModel();
participant.FullName = "John Smith";
participant.EmailAddress = "testing@alphatrust.com";
participant.SendRequestViaEmail = true;

t.Participants = new List<object> { participant };

var document = new DocumentInsertModel();
document.Title = "My Test Document";

var src = new SourceModel();
src.FileBytes = System.IO.File.ReadAllBytes(@"C:\MyDocument.pdf");

document.Source = src;

t.Documents = new List<object> { document };

var task = new TaskInsertModel();
var sigBlock = new SignatureBlockModel();
var sig = new SignatureModel();
var placement = new PdfSignaturePlacementModel();

task.Type = TaskInsertModel.TypeEnum.Signature;

sig.ApplicationType = SignatureModel.ApplicationTypeEnum.FontStamped;
sig.IsBold = true;
sig.IsItalic = true;

placement.PageCoordinatesPageNumber = 1;
placement.XOffset = 20;
placement.YOffset = 20;

sig.PdfPlacement = placement;
sigBlock.Signature = sig;
task.SignatureBlock = sigBlock;

// Assign the task to both the document and the participant
document.Tasks = new List<object> { task };
participant.Tasks = new List<object> { task };

// The values below will vary for your server's configuration
var apiKey = "MyCompanyInc";
var apiSecret = "4dda426f-134f-4a55-9dff-40f4c227e1a0";
var apiUsername = "my-api-user";
var apiPassword = "17334bae-5eff-4ee1-9a96-fa5dde6cbfc9";

var transactionList = new List<object> { t };

var req = new TransactionCreateRequestModel();
req.EnableLogging = true;
req.Transactions = transactionList;

var includes = new TransactionIncludesModel();
includes.ParticipantSigningUrl = true;
includes.DocumentId = true;
includes.ParticipantId = true;
req.ResponseIncludes = includes;

var myRestEndpointUrl = "https://my-esign-domain.com/rest";
var api = new TransactionsApi(myRestEndpointUrl);
var results = await api.CreateTransactionsAsync(req, apiKey, apiSecret, apiUsername, apiPassword);

if (results.IsSuccessful.Value)
{
    var transactionId = results.Transactions[0].TransactionID;
    var signingUrl = results.Transactions[0].Participants[0].SigningUrl;
    Console.WriteLine($"Transaction created: {transactionId}");
    Console.WriteLine($"Signing URL: {signingUrl}");
}
else
{
    Console.WriteLine($"Error creating transaction: {results.Message}");
}

Common Pitfalls

Task Assignment

The task MUST be assigned to both the document AND the participant. Forgetting either will cause the task to not appear or not be assigned correctly.

File Validation

The FileBytes must contain a valid PDF file. Corrupted or non-PDF files will cause errors.

Email Configuration

If SendRequestViaEmail = false, the participant won't receive an email even if you provide an email address. You'll need to send them the signing URL manually.

Production Logging

Always set EnableLogging = false in production environments to avoid account suspension.

Test Mode

When IsTest = true, transactions are marked as test data and may be automatically cleaned up. Use IsTest = false for production transactions.