Create an eSignature Transaction

This endpoint creates a new eSignature transaction, which represents a set of documents that need to be signed by one or more recipients. A transaction is the top-level container for managing the eSignature process. Authorization (http bearer token) is required.

Request Body — REQUIRED
documents object[] — REQUIRED List of documents id string id of the document from response from POST /document/upload title string — REQUIRED document title description string document description xfdf string document xfdf string StoragePath string — REQUIRED StoragePath of document from response POST /document/upload order number order the document is shown to participant pages number number of pages in the document readOnly boolean will this document be read only visible boolean will this document be visible to the participants tags object[] — REQUIRED List of tags to convert to xfdf type string — REQUIRED Possible values: [DATETEMPLATE, FULLNAMETEMPLATE, DOCUMENTIDTEMPLATE, NOTARYSESSIONIDTEMPLATE, COMMISSIONIDTEMPLATE, COMMISSIONEXPIRATIONTEMPLATE, DISCLAIMERTEMPLATE, COMMISSIONSTAMPTEMPLATE, SEALTAGTEMPLATEANNOTATION, NOTARYTITLETEMPLATE, NOTARYCOUNTYTEMPLATE, NOTARYSTATETEMPLATE, SIGNATURETEMPLATE, SIGNHERETAGTEMPLATEANNOTATION, INITIALSTEMPLATE, INITIALHERETAGTEMPLATEANNOTATION, FREEFORMTEXTTAGTEMPLATEANNOTATION, TEXTANNOT] x number — REQUIRED bottom-left x-coordinate of the tag annotation y number — REQUIRED bottom-left y-coordinate of the tag annotation width number — REQUIRED width of the tag annotation height number — REQUIRED height of the tag annotation signerId string — REQUIRED id of the signer this tag is assigned to customData object — REQUIRED page number — REQUIRED page number of the tag annotation required boolean tag is required to be applied stateFormat string tag is required to be applied dateFormat string Possible values: [MM/DD/YYYY, DD/MM/YYYY, MM/DD/YY, DD/MM/YY, MMMM do, yyyy, full, MMMM, do, yyyy, YYYY] tag is required to be applied fontSize number tag font size
participants object[] — REQUIRED list of participants to include in esign session id string — REQUIRED id of the signer this tag is assigned to order number order of participant email string — REQUIRED email of the signer firstName string — REQUIRED first name of signer middleName string middle name of signer lastName string — REQUIRED last name of signer address1 string address of signer address2 string address 2 of signer country string country of signer city string address 2 of signer state string state of signer zip string postal code of signer phone string phone number of signer kbaRequired boolean is KBA required for this signer credAnalysisRequired boolean is credential-analysis required for this signer externalId string consumer-provided external id authenticationType string — REQUIRED Possible values: [personal-password, two-factor-authentication, none] twoFactorContact string — REQUIRED Possible values: [sms, email] personalPasswordQuestion string personalPassword string inviteEmailSubject string viewOnly boolean Request field. When true, this participant is a view-only recipient who can access and view documents but cannot sign, fill in tags, or modify any document content. View-only recipients do not block transaction completion, and tags may not be assigned to them (doing so returns a 400). Setting viewOnly=true automatically makes the participant a non-signer. role string Response field. The resolved role of the participant: "signer", "non-signer", "view-only", or a custom role name from a template. viewStatus string Possible values: [pending, viewed] Response field. View status of a view-only participant: "pending" if they have not yet viewed the documents, "viewed" if they have. Present only for view-only participants. viewedAt date-time Response field. ISO 8601 timestamp of when a view-only participant first viewed the documents, or null if not yet viewed. Present only for view-only participants.
notifyParticipants object notification preferences email boolean send email notification to participants
status string — REQUIRED Possible values: [draft, esign_pending]
referenceId string — REQUIRED The unique identifier your organization assigned to this transaction.
signingOrder boolean The flag to enable signing order.
personalizedMessage string Custom email message body included in the signing invitation email.
emailSubject string Possible values: length ≤ 255 Custom email subject line for signer notification emails. Maximum 255 characters. If omitted, the system default subject is used.
brandId uuid Optional UUID of the brand to apply to this transaction. Must belong to your organization.
showConfetti boolean V2-12387 — Whether to play a confetti animation for the signer after signing completes. No feature flag required.
useReplyTo boolean V2-12387 — Whether outgoing eSign emails include a Reply-To header. Requires the enableReplyTo feature flag. NOTE: when this transaction also has a brandId and that brand has email config enabled, the brand's Reply-To takes precedence and these fields will not be used in outgoing emails. See the GET response's replyToOverriddenByBrand and effectiveReplyTo for what will actually be applied.
replyToEmail email Possible values: length ≤ 255 V2-12387 — Reply-To address used in outgoing eSign emails when useReplyTo is true. Requires the enableReplyTo feature flag. May be overridden by brand Reply-To — see effectiveReplyTo on the GET response.
assignedGroupId uuid V2-12387 — UUID of the team/group within your organization to assign this transaction to. Requires the teamAssignment feature flag. Use GET /teams to discover available team IDs.
allowSignerNameEdit boolean V2-12387 — Whether signers can edit their own name during the signing process. Requires the signersNameEdit feature flag.
fileReference string Possible values: length ≤ 255 V2-12387 — An identifier you can use to track this transaction. Distinct from referenceId; stored on the Transaction record.

Responses
201 The record has been successfully created. Schema — OPTIONAL taggingOrganizationId string — OPTIONAL id of the organization assigned to tag this document evault string — OPTIONAL Possible values: [eOriginal] eVault to use. Defaults to eOriginal sendFinalEnoteTo string[] Possible values: [eOriginal] documents object[] List of documents id string — OPTIONAL id of the document from response from POST /document/upload title string document title description string — OPTIONAL document description xfdf string — OPTIONAL document xfdf string StoragePath string StoragePath of document from response POST /document/upload order number — OPTIONAL order the document is shown to participant pages number — OPTIONAL number of pages in the document readOnly boolean — OPTIONAL will this document be read only visible boolean — OPTIONAL will this document be visible to the participants tags object[] List of tags to convert to xfdf type string Possible values: [DATETEMPLATE, FULLNAMETEMPLATE, DOCUMENTIDTEMPLATE, NOTARYSESSIONIDTEMPLATE, COMMISSIONIDTEMPLATE, COMMISSIONEXPIRATIONTEMPLATE, DISCLAIMERTEMPLATE, COMMISSIONSTAMPTEMPLATE, SEALTAGTEMPLATEANNOTATION, NOTARYTITLETEMPLATE, NOTARYCOUNTYTEMPLATE, NOTARYSTATETEMPLATE, SIGNATURETEMPLATE, SIGNHERETAGTEMPLATEANNOTATION, INITIALSTEMPLATE, INITIALHERETAGTEMPLATEANNOTATION, FREEFORMTEXTTAGTEMPLATEANNOTATION, TEXTANNOT] x number bottom-left x-coordinate of the tag annotation y number bottom-left y-coordinate of the tag annotation width number width of the tag annotation height number height of the tag annotation signerId string id of the signer this tag is assigned to customData object page number page number of the tag annotation required boolean — OPTIONAL tag is required to be applied stateFormat string — OPTIONAL tag is required to be applied dateFormat string — OPTIONAL Possible values: [MM/DD/YYYY, DD/MM/YYYY, MM/DD/YY, DD/MM/YY, MMMM do, yyyy, full, MMMM, do, yyyy, YYYY] tag is required to be applied fontSize number — OPTIONAL tag font size participants object[] list of participants to include in esign session id string id of the signer this tag is assigned to order number — OPTIONAL order of participant email string email of the signer firstName string first name of signer middleName string — OPTIONAL middle name of signer lastName string last name of signer address1 string — OPTIONAL address of signer address2 string — OPTIONAL address 2 of signer country string — OPTIONAL country of signer city string — OPTIONAL address 2 of signer state string — OPTIONAL state of signer zip string — OPTIONAL postal code of signer phone string — OPTIONAL phone number of signer kbaRequired boolean — OPTIONAL is KBA required for this signer credAnalysisRequired boolean — OPTIONAL is credential-analysis required for this signer externalId string — OPTIONAL consumer-provided external id authenticationType string Possible values: [personal-password, two-factor-authentication, none] twoFactorContact string Possible values: [sms, email] personalPasswordQuestion string — OPTIONAL personalPassword string — OPTIONAL inviteEmailSubject string — OPTIONAL viewOnly boolean — OPTIONAL Request field. When true, this participant is a view-only recipient who can access and view documents but cannot sign, fill in tags, or modify any document content. View-only recipients do not block transaction completion, and tags may not be assigned to them (doing so returns a 400). Setting viewOnly=true automatically makes the participant a non-signer. role string — OPTIONAL Response field. The resolved role of the participant: "signer", "non-signer", "view-only", or a custom role name from a template. viewStatus string — OPTIONAL Possible values: [pending, viewed] Response field. View status of a view-only participant: "pending" if they have not yet viewed the documents, "viewed" if they have. Present only for view-only participants. viewedAt date-time — OPTIONAL Response field. ISO 8601 timestamp of when a view-only participant first viewed the documents, or null if not yet viewed. Present only for view-only participants.
400 The request is invalid Schema — OPTIONAL error object statusCode number status code message string[] List of documents error string status code