Data Importer CSV File Setup

Modified on: Wed, Aug 31, 2022 at 1:57 PM

The Data Importer tool allows you to add an entire batch of contacts or loans to a Total Expert (TE) account in a single bulk action. This means you can now bring your data from another system into the TE platform without submitting a request with customer support.

The Data Importer tool is meant to be used only by system administrators and must be activated by TE for these users in your organization.

Before you can import contact or loan data into the Total Expert platform, you must first set up the data file to be imported. This document only covers requirements and setup instructions for the import file; see Using the Data Importer for instructions on importing the data into the platform.

Import File Requirements

Regardless of whether you are importing contacts or loans, the import file must satisfy the following constraints:

The data to be imported must be stored in a comma-separated variable (CSV) file.
The first row of the CSV file must consist of column headers, which are used to map to TE fields.

When an import file contains multiple contact or loan records with the same identifying data, those records will be merged into a single record. A record whose identifying data matches an existing contact or loan in TE will update the existing record with the data in the import file, including overwriting data in the existing record.

Some fields may be left blank for some or all contacts or loans in an import file. As long as the minimum requirements are met for each record, blank fields will not disrupt the import process.

Minimum Information for Contact Imports

When importing a list of contacts, each record must have at least the following data to be considered complete:

first name
last name (must be in a separate column of the CSV file from first name)
at least one of:
email address
phone number (home, cell, or office number)
physical address (must include street address, city, state, and ZIP code in separate columns)

Minimum Information for Loan Imports

When importing a list of loans, each record must have at least the following data to be considered complete:

loan number
borrower’s first name
borrower’s last name (must be in a separate column of the CSV file from first name)
at least one of:
borrower’s email address
borrower’s phone number (home, cell, or office number)
borrower’s physical address (must include street address, city, state, and ZIP code in separate columns)

Duplicate Checking

Contacts or loans in the CSV file that do not already exist in the target user’s database will be created as new records. If no creation date is specified, the date of the import will be written to this field.

If a record in a contact import exactly matches the full name and at least one part of the contact information for an existing record, it will be considered a duplicate of the existing record. In this case, a new record will not be created, and the existing record will be updated with any data in the imported file. Blank fields in the import file will not overwrite fields that contain existing data.

Setup Instructions

1. Collect the data you want to import into a single file in Microsoft Excel (or other program that can save data as a CSV file).

You might do this by exporting the list from another system or by manual entry from other sources.

Tip

A single CSV file to be imported should have no more than 7,500 records to avoid having the import time out. If you have more records to import, break them into multiple files and import each separately.

2. Ensure that the first row in the file consists of column headers.

You have 2 options for setting up these headers:

Use header names exactly as given in the verified template files; these names are listed in the Column Header Names section below. This allows you to map the headings to TE fields while running the import by simply clicking the Apply Defaults button.
Use any header names that are sufficiently descriptive that they can be easily identified. This will require a manual selection to map each header to a corresponding TE field while running the import.

Tip
TE recommends using the first option. It may require more work at this stage, but it makes mapping fields during the import a one-click step. You can then use the resulting file as a template for future imports.

The contacts template and loans template are available to download from the import list page (Organization Admin [Symbol] Data Importer) by clicking the template download buttons. You can use these files directly or copy the headers and paste them into your existing file.

3. Save the file in CSV format

The file is now ready to import. See Using the Data Importer for instructions on running the import in the platform.

If you are having difficulty with the setup or import, please contact Customer Support.

Column Header Names

Use the tables below to locate the appropriate header names to add to your CSV file so the columns will map to the correct TE fields when you run the import. Required fields are highlighted.

For most fields, whatever data you provide in each field will be imported as-is; the importer does not validate the contents of these fields. In some cases, as noted below, certain values or formats are expected. In these cases, “bad” data will be treated as described.

Ensure that all the dates in a single CSV file are formatted the same way. The import process includes a step to select the date format the importer should look for; any data formatted any other way will not be interpreted as a date and will not be imported. This applies to both contact and loan imports.

Ensure that the data is accurate, formatted as expected, and given the correct headings before using the Data Importer.

User-Identifying Headers

When setting up your CSV file to import records to multiple users, you must include a column that identifies which user each record should be a imported for. These headers are not included in the templates, so you would have to add the column manually.

If the user the record applies to is identified by email address, use the column header user.email.

If the user the record applies to is identified by external ID, use the column header user.external_id.

Note

A single CSV file should only include one or the other of these, not both.

Headers for Contact Records

For the most part, the field names given in the contacts template are self-explanatory. Notes are given below where the purpose of a field or formatting of the data you provide warrants some explanation. If a record in the CSV file does not include enough information to create a new contact record in TE, that record will be skipped.

Contact Template Field Name	Notes
contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
contact-note.notes	Text to be saved as a general note on the contact record. All the text in this field is added to a single note.
contact.external_id
contact.title	For example, Mr., Mrs., or Captain.
contact.first_name
contact.last_name
contact.suffix	For example, Sr., Jr., or III.
contact.email	The contact’s primary email address.
contact.email_work	A secondary email address. This will be used if the primary address is blank.
contact.ok_to_email	A value that determines whether the system will allow or suppress emails to this contact. A value of yes or 1 here will allow emails to be sent. Any other value (including blank) will be interpreted as opted out.
contact.address
contact.address_2
contact.city
contact.state	Use the 2-character postal code. If anything else is provided, such as full state names, the field will be left blank in TE.
contact.zip
contact.ok_to_mail	A value that determines whether the system will allow or suppress physical mail to this contact. A value of yes or 1 here will allow mail to be sent. Any other value (including blank) will be interpreted as opted out.
contact.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
contact.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
contact.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
contact.fax
contact.ok_to_call	A value that determines whether the system will allow or suppress calls to this contact. A value of yes or 1 here will allow calls to be made. Any other value (including blank) will be interpreted as opted out.
contact.employer
contact.employer_address
contact.employer_address_2
contact.employer_city
contact.employer_state
contact.employer_zip
contact.employer_license_number
contact.license_number
contact.lead_source	Text indicating the way the contact was discovered. If a source name does not already exist, it will be created.
contact.creation_date	The date the record was created. If blank or incorrectly formatted, the date the import is performed will be written to this field in TE.
contact.last_modified_date	The date the record was most recently changed. If blank or incorrectly formatted, the field will be left blank in TE.
contact.birthday	The contact’s date of birth. If blank or incorrectly formatted, the field will be left blank in TE. Depending on your organization’s setup, the year may be suppressed.
contact.last_contacted_date	The date the contact was most recently contacted (by any means). If blank or incorrectly formatted, the field will be left blank in TE.
contact.referred_to	The name of the person to whom this contact has been referred.
contact.referred_by	The name of the person who referred this contact to you.
contact.list_date	The date the contact’s property was listed. If blank or incorrectly formatted, the field will be left blank in TE.
contact.close_date	The date the contact’s loan was closed. If blank or incorrectly formatted, the field will be left blank in TE.
contact.credit_score	Valid values are Excellent, Good, Fair, Poor, and Very Poor. If anything else is provided, such as numeric values, the field will be left blank in TE.
contact.credit_score_date	The date the contact’s credit score was checked. If blank or incorrectly formatted, the field will be left blank in TE.
contact.credit_score_expiration_date	The date the contact’s current credit score expires. If blank or incorrectly formatted, the field will be left blank in TE.

Headers for Loan Records

For the most part, the field names given in the loans template are self-explanatory. Notes are given below where the purpose of a field or formatting of the data you provide warrants some explanation. The loan fields below are broken into multiple sections to help you locate different types of fields.

Loan-Related Headers

These headers refer to information about the loan itself. The loan number is required information for an import. If a record in the CSV file does not include this, that record will be skipped.

Loan Template Field Name	Description
referring-loan-officer.external_id
loan-status.status	The current status of the loan, such as New or Clear to Close. If a status name does not already exist, it will be created.
loan-program.program	The program of the loan, such as 15-Year Fixed or 10-Year ARM. If a program name does not already exist, it will be created.
loan-type.type	The type of the loan, such as Conventional or VA. If a type name does not already exist, it will be created.
loan-purpose.purpose	The purpose of the loan, such as Purchase or Refinance. If a type name does not already exist, it will be created.
loan.external_id
loan.address
loan.address_2
loan.city
loan.state
loan.zip	Value must be numeric.
loan.county
loan.estimated_value
loan.appraised_value
loan.purchase_price
loan.amount
loan.rate	The percentage rate of the loan. The number provided will be rounded to the nearest .001%. For example, entering 1.0046 will be interpreted as 1.005%.
loan.term	Number of months for the borrower to pay back the loan. If a non-integer is entered, the value will be rounded to the nearest integer.
loan.loan_name
loan.loan_number
loan.application_number
loan.application_date
loan.application_sent_date
loan.application_received_date
loan.is_first_time_buyer	A value of yes or 1 here indicates the borrower is a first-time home buyer. Any other value will be interpreted as no.
loan.property_type
loan.pre_approval_issued	A value of yes or 1 here indicates the borrower was issued a pre-approval. Any other value will be interpreted as no.
loan.pre_approval_issued_date
loan.pre_approval_expiration_date
loan.approval_date
loan.loan_to_value_combined
loan.occupancy_type
loan.escrow_waived	A value of yes or 1 here indicates that escrow was waived. Any other value will be interpreted as no.
loan.lock_status
loan.lock_date
loan.lock_expiration_date
loan.appraisal_expected_date
loan.appraisal_ordered_date
loan.appraisal_received_date
loan.created_date
loan.ctc_date
loan.closing_date
loan.documents_signed_date
loan.epo_date
loan.first_payment_date
loan.funded_date
loan.loan_arm_expiration_date
loan.processing_start_date
loan.underwriting_submission_date
loan.underwriting_approval_date
loan.annual_review_date
loan.last_modified_date
loan.referral_source

Borrower-Related Headers

The following loan headers relate specifically to the primary borrower. The borrower’s first name, last name, and one distinct type of contact information are required information for the loan record import to succeed. If the borrower’s information does not match an existing contact record in the target user’s list, a new contact record will be created. If insufficient information is provided (for example, just first and last name), no contact will be created, and the loan record import will be skipped.

Loan Template Field Name	Description
borrower-contact-note.notes	Text to be saved as a general note on the contact record. All the text in this field is added to a single note.
borrower-contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
borrower.external_id
borrower.title	For example, Mr., Mrs., or Captain.
borrower.first_name
borrower.last_name
borrower.suffix	For example, Sr., Jr., or III.
borrower.email	The contact’s primary email address.
borrower.email_work	A secondary email address. This will be used if the primary address is blank.
borrower.ok_to_email	A value that determines whether the system will allow or suppress emails to this contact. A value of yes or 1 here will allow emails to be sent. Any other value (including blank) will be interpreted as opted out.
borrower.address
borrower.address_2
borrower.city
borrower.state
borrower.zip
borrower.ok_to_mail	A value that determines whether the system will allow or suppress physical mail to this contact. A value of yes or 1 here will allow mail to be sent. Any other value (including blank) will be interpreted as opted out.
borrower.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
borrower.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
borrower.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
borrower.fax
borrower.ok_to_call	A value that determines whether the system will allow or suppress calls to this contact. A value of yes or 1 here will allow calls to be made. Any other value (including blank) will be interpreted as opted out.
borrower.employer
borrower.employer_address
borrower.employer_address_2
borrower.employer_city
borrower.employer_state
borrower.employer_zip
borrower.lead_source	Text indicating the way the contact was discovered. If a source name does not already exist, it will be created.
borrower.creation_date	The date the record was created. If blank or incorrectly formatted, the date the import is performed will be written to this field in TE.
borrower.last_modified_date	The date the record was most recently changed. If blank or incorrectly formatted, the field will be left blank in TE.
borrower.birthday	The contact’s date of birth. If blank or incorrectly formatted, the field will be left blank in TE. Depending on your organization’s setup, the year may be suppressed.
borrower.last_contacted_date	The date the contact was most recently contacted (by any means). If blank or incorrectly formatted, the field will be left blank in TE.
borrower.referred_to	The name of the person to whom this contact has been referred.
borrower.referred_by	The name of the person who referred this contact to you.
borrower.credit_score	Valid values are Excellent, Good, Fair, Poor, and Very Poor. If anything else is provided, such as numeric values, the field will be left blank in TE.
borrower.credit_score_date	The date the contact’s credit score was checked. If blank or incorrectly formatted, the field will be left blank in TE.
borrower.credit_score_expiration_date	The date the contact’s current credit score expires. If blank or incorrectly formatted, the field will be left blank in TE.

Co-Borrower–Related Headers

The following loan headers relate specifically to the co-borrower. If the co-borrower’s information does not match an existing contact record in the target user’s list and enough information to create a record is provided, a new contact record will be created. If insufficient information is provided (for example, just first and last name), no contact will be created, but the loan record import will still succeed.

Loan Template Field Name	Description
coborrower-contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
coborrower.external_id
coborrower.title	For example, Mr., Mrs., or Captain.
coborrower.first_name
coborrower.last_name
coborrower.suffix	For example, Sr., Jr., or III.
coborrower.email	The contact’s primary email address.
coborrower.email_work	A secondary email address. This will be used if the primary address is blank.
coborrower.ok_to_email	A value that determines whether the system will allow or suppress emails to this contact. A value of yes or 1 here will allow emails to be sent. Any other value (including blank) will be interpreted as opted out.
coborrower.address
coborrower.address_2
coborrower.city
coborrower.state
coborrower.zip
coborrower.ok_to_mail	A value that determines whether the system will allow or suppress physical mail to this contact. A value of yes or 1 here will allow mail to be sent. Any other value (including blank) will be interpreted as opted out.
coborrower.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
coborrower.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
coborrower.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
coborrower.fax
coborrower.ok_to_call	A value that determines whether the system will allow or suppress calls to this contact. A value of yes or 1 here will allow calls to be made. Any other value (including blank) will be interpreted as opted out.
coborrower.employer
coborrower.employer_address
coborrower.employer_address_2
coborrower.employer_city
coborrower.employer_state
coborrower.employer_zip
coborrower.lead_source	Text indicating the way the contact was discovered. If a source name does not already exist, it will be created.
coborrower.creation_date	The date the record was created. If blank or incorrectly formatted, the date the import is performed will be written to this field in TE.
coborrower.last_modified_date	The date the record was most recently changed. If blank or incorrectly formatted, the field will be left blank in TE.
coborrower.birthday	The contact’s date of birth. If blank or incorrectly formatted, the field will be left blank in TE. Depending on your organization’s setup, the year may be suppressed.
coborrower.last_contacted_date	The date the contact was most recently contacted (by any means). If blank or incorrectly formatted, the field will be left blank in TE.
coborrower.referred_to	The name of the person to whom this contact has been referred.
coborrower.referred_by	The name of the person who referred this contact to you.
coborrower.credit_score	Valid values are Excellent, Good, Fair, Poor, and Very Poor. If anything else is provided, such as numeric values, the field will be left blank in TE.
coborrower.credit_score_date	The date the contact’s credit score was checked. If blank or incorrectly formatted, the field will be left blank in TE.
coborrower.credit_score_expiration_date	The date the contact’s current credit score expires. If blank or incorrectly formatted, the field will be left blank in TE.

Buyer’s Agent–Related Headers

The following loan headers relate specifically to the buyer’s agent. If the buyer’s agent’s information does not match an existing contact record in the target user’s list and enough information to create a record is provided, a new contact record will be created. If insufficient information is provided (for example, just first and last name), no contact will be created, but the loan record import will still succeed.

Loan Template Field Name	Description
buyers_agent-contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
buyers_agent.external_id
buyers_agent.first_name
buyers_agent.last_name
buyers_agent.email	The contact’s primary email address.
buyers_agent.email_work	A secondary email address. This will be used if the primary address is blank.
buyers_agent.address
buyers_agent.address_2
buyers_agent.city
buyers_agent.state
buyers_agent.zip
buyers_agent.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
buyers_agent.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
buyers_agent.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
buyers_agent.fax
buyers_agent.employer
buyers_agent.employer_address
buyers_agent.employer_address_2
buyers_agent.employer_city
buyers_agent.employer_state
buyers_agent.employer_zip
buyers_agent.employer_license_number
buyers_agent.license_number

Seller’s Agent–Related Headers

The following loan headers relate specifically to the seller’s agent. If the seller’s agent’s information does not match an existing contact record in the target user’s list and enough information to create a record is provided, a new contact record will be created. If insufficient information is provided (for example, just first and last name), no contact will be created, but the loan record import will still succeed.

Loan Template Field Name	Description
sellers_agent-contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
sellers_agent.external_id
sellers_agent.first_name
sellers_agent.last_name
sellers_agent.email	The contact’s primary email address.
sellers_agent.email_work	A secondary email address. This will be used if the primary address is blank.
sellers_agent.address
sellers_agent.address_2
sellers_agent.city
sellers_agent.state
sellers_agent.zip
sellers_agent.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
sellers_agent.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
sellers_agent.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
sellers_agent.fax
sellers_agent.employer
sellers_agent.employer_address
sellers_agent.employer_address_2
sellers_agent.employer_city
sellers_agent.employer_state
sellers_agent.employer_zip
sellers_agent.employer_license_number
sellers_agent.license_number

Settlement Agent–Related Headers

The following loan headers relate specifically to the settlement agent. If the settlement agent’s information does not match an existing contact record in the target user’s list and enough information to create a record is provided, a new contact record will be created. If insufficient information is provided (for example, just first and last name), no contact will be created, but the loan record import will still succeed.

Loan Template Field Name	Description
settlement_agent-contact-group.name	List of groups the contact should belong to in TE. If a group name does not already exist, it will be created. Add multiple groups by separating the names with commas (and no spaces). For example: clients,in process.
settlement_agent.external_id
settlement_agent.first_name
settlement_agent.last_name
settlement_agent.email	The contact’s primary email address.
settlement_agent.email_work	A secondary email address. This will be used if the primary address is blank.
settlement_agent.address
settlement_agent.address_2
settlement_agent.city
settlement_agent.state
settlement_agent.zip
settlement_agent.phone_cell	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
settlement_agent.phone_office	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
settlement_agent.phone_home	If the format is anything other than (###) ###-####, the text will be imported as-is, but will be flagged as incorrectly formatted on the contact details page.
settlement_agent.fax
settlement_agent.employer
settlement_agent.employer_address
settlement_agent.employer_address_2
settlement_agent.employer_city
settlement_agent.employer_state
settlement_agent.employer_zip
settlement_agent.employer_license_number
settlement_agent.license_number