Driven by Code
Published in

Driven by Code

How We Built the eSignature Step in TrueCar+

By: Rohan Mendon

Looking into the future, the Holy Grail of any modern car-buying experience for consumers and dealers is to allow consumers to complete their entire purchase online.

To move towards achieving that experience, we launched TrueCar+, which is currently live in the state of Florida. One of this product’s essential steps is eSignature, which involves presenting the consumer with a Buyer’s Order (using DocuSign) to review and sign. This is similar to other products already in the market in different business segments, like mortgage refinancing, where consumers review and sign documents online.

What Is a Buyer’s Order?

A Buyer’s Order is a document that lists all details about the potential sale of a vehicle from an auto dealership to a buyer, and it includes information about the buyer(s), dealership, vehicle, trade-in, breakdown of the vehicle’s total sale price including taxes & fees, and all other details applicable to the transaction.

Also importantly, this document isn’t a legally binding agreement and that signing one isn’t the final step in a car buying transaction, but a Bill of Sale is needed for the transaction to bind both parties to complete the deal.

Below are screen captures of a consumer’s view of the Buyer’s Order ready for eSignature in TrueCar+. On page 1 of the Buyer’s Order, we show the buyer’s and the co-buyer’s contact information, along with the seller’s/dealership’s contact information and the vehicle information. On page 2, we show the detailed price breakdown.

In this blog, I’m going to cover how we leveraged DocuSign to build the eSignature step, starting with using DocuSign’s eSignature Concepts and their UI to set up the document templates, then utilizing TrueCar’s application architecture and data modeling to build this feature, and finally showing the eSignature in action.

High-Level eSignature Concepts (from DocuSign)

DocuSign’s high-level data models are composed of the following entities:

  1. Envelopes An Envelope object (an instance) is the overall container for a DocuSign transaction, which includes Document(s) and Recipient(s).
  2. Templates A Template is a blueprint to create one or more Envelopes.
  3. Documents A Document is an object that contains a digital document file (for example, a blank PDF) and a set of metadata describing that document file.
  4. Tabs Tabs are locations in a Document where a Recipient must provide input (typically signature fields).
  5. Recipients A Recipient (a.k.a., Signers) object refers to a user who receives a DocuSign Envelope for signing.

Template Setup (in DocuSign’s UI)

The first step is to create a template (Pic 4) in DocuSign and upload an original blank Buyer’s Order document in PDF format (Pic 5) to that template. Then we need to configure the signing orders (Pic 5) by roles to that template — in our case, Dealer (first) and Consumer (second). Finally, we configure the placeholder fields (Pic 6) to be populated with real-time data (via APIs at a later time). The placeholder fields include text fields, signature fields, and file attachment upload fields. DocuSign also allows fields to be configured at the role level, allowing us to have dealer-specific and consumer-specific fields (including signature fields) at various locations in the document.

High-Level System Architecture Diagram

The following diagram (Pic 7) describes TrueCar’s applications architecture, where we have the dealer-facing front-end app (known as Dealer Portal) and the consumer-facing front-end app calling the same back-end app, which then interacts with DocuSign via APIs.

For the dealer’s eSignature step, the document for signing is presented in Dealer Portal, whereas for the consumer’s eSignature step, the document for signing is presented in the TrueCar+ flow.

High-Level Data Modeling Diagram

In our case (Pic 8), each dealership can have their own version of the Buyer’s Order. Hence, we needed to map templates to dealerships. Since both dealership employees and consumers need to sign documents, we have a Recipients table to capture that mapping and the main Envelopes table that references Recipients. Our TC+ Order can have many Envelopes associated because Envelopes can be voided by either the dealer or the consumer during the transaction if any data needs to be corrected. In these cases, the data is updated in Dealer Portal, and a new Envelope is generated for signing. In the Envelopes/Recipients/Templates model, we have references to DocuSign’s Envelope IDs, Recipients IDs, and Template IDs, respectively. This is needed to look up information in DocuSign and persist statuses in our system. The Document Parameters model refers to the individual data fields; for example, the price breakdown, passed in the Envelope Creation API, to be rendered on the final document to be presented to users for review and signing.

eSignature in Action

Once the consumer lands on the eSignature step in TrueCar+, we begin the signing experience by notifying the dealer to prepare the Buyer’s Order. The dealer confirms the individual data fields for the Buyer’s Order, then generates the Envelope and signs the Buyer’s Order, all in Dealer Portal. After the dealer has finished signing, we notify the consumer that there is a Buyer’s Order ready for review and signature. Once the consumer has reviewed and signed, the eSignature step is marked as complete and progresses to the next step in the TrueCar+ flow.

Generating the Envelope entails creating a DocuSign Envelope Definition, which consists of a Template, Webhook configurations, Signers (aka Recipients), and, for each signer, the data for the placeholder fields (aka Tabs).

The Webhook configuration is needed so that TrueCar can receive event notifications about this specific Envelope. We used ngrok as a reverse proxy to expose localhost to the Internet for local development. These notifications allow us to receive real-time updates when the dealer and consumer sign the documents and to decide the next business action to be taken in our back-end system. The Webhook configuration is part of the Envelope, and it can support sending Webhook notifications to our numerous ephemeral environments.

Because of our product requirements, we need to render the Buyer’s Order in a modal. DocuSign’s document signing page is displayed in an iFrame. We also need to send TrueCar-branded emails (to both dealer and consumer) with links back to the Buyer’s Order on the TrueCar+ order page. To achieve this goal, we set up an Embedded Signer, which allows the signing ceremony to happen on our own website.

As we added more features, we switched to using Composite Templates, where we stitched together two templates containing just one document at the time of Envelope creation. This helped us with reusing documents.

DocuSign provides two environments:

  1. A Developer account at
  2. Production account at

All of our non-production (including local) environments are integrated with DocuSign’s Developer account. Only our Production environment uses DocuSign’s Production account.

DocuSign’s API documentation is very detailed. We liked their Quickstart tool, which generates a zipped file with lots of examples in the language of your choosing (in our case, Ruby). DocuSign also provides client SDKs in the language of your choosing. We used the eSignature Ruby Client SDK.

Here is an example of our Envelope Definition. We call the createEnvelope API with this Envelope Definition as a parameter.

Note: ActiveInteraction::Base is the base class from active_interaction gem. We use this pattern of Interaction Classes to encapsulate specific business logic.

Following is a sample Webhook response from DocuSign, and you see the various data fields.

Final Thoughts

Buying a car is a complex process involving multiple parties. Moving it to an online model streamlines this process for both consumers and dealers, and moving paperwork-related action items online reduces complexity, ultimately improving user experience.

It was easy to incorporate DocuSign as an eSignature facilitator for the Buyer’s Order in TrueCar+. Incorporating this process increased our brand value.

We are hiring! If you love solving problems, please apply here. We would love to have you join us!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Driven by Code

Welcome to TrueCar’s technology blog, where we write about the interesting things we‘re working on. Read, engage, and come work with us!