Overview

The TWP Integration supports importing of data using CSV files. This document describes the format of the CSV file and the process for importing it.

CSV File Format

Basic Format

  • The CSV file must be an ASCII text file. Unicode characters are not supported.
  • Each line of the CSV file must end with a carriage return line feed combination (ASCI 13, and 10).
  • The first row in the file must be a header row consisting of the fields you are including.
  • Carriage returns and line feeds cannot exist in any data fields.
  • A carriage return/line feed is not required on the last row of data (but is allowed)
  • Any blank line in the file is ignored.
  • The following fields are required in every file. Other fields are optional.
    1. UniqueID
    2. PrimaryAccountName
    3. PrimaryFirstName
    4. PrimaryLastName
  • Any field not included is treated as if you set it to its default value.
    1. boolean: false
    2. string: blank
    3. date: blank
    4. number: zero or blank

Naming Conventions

  • Every file must have a unique name. We recommend using a date or time stamp.

Data Formats

  • Dates must be in the format YYYY-MM-DD.
  • Boolean fields can be either “true” or “false”. A value of blank (“”) will be treated as “false”.
  • Custom fields are treated as text fields so you may use any format you want to indicate dates (i.e. “Monday, May 5th, 2020”).

Header Row

The header row (the first row in the file) may contain any number of field names from the list of supported fields (see below). There is no specific order required for the fields. The field names are case sensitive. Any field name that is not recognized will cause an error. You may also include any number of custom fields. (See Custom Fields section below.)

Custom Fields

In addition to the supported fields, you may have any number of custom fields. All custom fields are treated as text and will show up exactly how you supply them. Custom fields must be prefixed with and asterisk (*). This lets the import know that it is not a standard field. Custom fields should not reuse any existing field names. They should contain only letters and numbers. Examples are show below:

  • *LoanType
  • *LegalDisclosure
  • *Address2

Payment Fields

Each payment consists of 3 fields which are all combined to make up a payment record. The 3 fields are:

  • PaymentAmt
  • PaymentDate
  • PaymentDesc

Each consumer record may have up to 100 payments. When specifying payments, start with the suffix of ‘1’ for each field name and increment it for each payment. You do not need to put the payments in any specific order. The system will sort them by date regardless the order in the data file. The Amount and Date fields are required for each payment. The Description field is optional.

Examples

Below is an example of the payment fields in a record:

================
PaymentAmt1,PaymentDate1,PaymentAmt1,PaymentntDate2,PaymentDesc1,PaymentDesc2
 
100.00,2020-01-15,150.00,2020-02-15,Check Payment,Online Payment
================

Post Date Fields

Post Dates use the same logic as Payments except their fieldnames are:

  • PostDateAmt
  • PostDateDate
  • PostDateDesc

Example Files

Below are multiple examples of file that contain only one record (for simplicity). Your file can contain any number of fields and records. Because of word wrap, some records appear to extend onto multiple lines. That would not be the case when saving in a CSV file.

Example 2 – Simple File:

================
Unique, UniqueID,PrimaryAccountName,PrimaryFirstName,PrimaryLastName
12345,John Doe,John,Doe
 ================

Example 2 – More Fields:

================
UniqueID,PrimaryAccountName,PrimaryFirstName,PrimaryLastName,CurrentBalance,AllowConsumerToAccess,AcceptCheckingPayment,AcceptCreditCardPayment,OriginalCreditor
12345,John Doe,John,Doe,2000.55,true,true,false,ACME Credit
 ================

Example 3 – With Custom Fields:

================
UniqueID,PrimaryAccountName,PrimaryFirstName,PrimaryLastName,CurrentBalance,AllowConsumerToAccess,AcceptCheckingPayment, AcceptCreditCardPayment,OriginalCreditor,*CoBorrowerName,*AccountType
12345,John Doe,John,Doe,2000.55,true,true,false,ACME Credit,Jane Doe,Loan
 ================

Standard Fields

Name

Type

Description

UniqueID (required)

String

A unique identifier for each account. Sometimes called the Reference Number or account number. This should never change.

AllowConsumerToAccess

Bool

Allows the consumer to view the account information. If this is set to true a user sees their account information. When set to false, some of their information will show up as “unavailable” and they will not be able to make payment. This can be used to disable access to a single account without removing it.

PrimaryAccountName (required)

String

Complete name of primary account holder

PrimaryFirstName (required)

String

First name of the primary account holder

PrimaryLastName (required)

String

Last name of the primary account holder

Address

String

Address of account holder

City

String

City of account holder

State

String

State of account holder

Zip

String

Zip code of account holder

Email

String

The email address for the account holder

SSN

String

Social security number (or the last 4 of the SSN)

DOB

Date

Date of birth

AssignedBalance

Decimal

The beginning balance when the account was assigned

AssignedDate

Date

The date the account was assigned

CurrentBalance

Decimal

The current balance on the account

CanMakePayment

Bool

Can the user make a payment on this account? By default, they will be prevented from making a payment, if the balance is zero. However, you can prevent payments for other reasons (i.e. Complaint, Settlement, already scheduled payments).

AcceptCheckingPayment

Bool

True if single ACH Payments are allowed. False otherwise.

AcceptCreditCardPayment

Bool

True if credit cards will be accepted for this account, false otherwise. 

AcceptDebitCardPayment

Bool

True if debit cards will be accepted for this account, false otherwise. (bin detection component required)

AcceptRecurringCheckingPayment

Bool

True if recurring checking account (ACH) payments are allowed

AcceptRecurringCreditCard

Bool

True if recurring credit card payments are allowed (must be supported by your gateway)

AcceptRecurringDebitCard

Bool

True if recurring debit card payments are allowed (must be supported by your gateway)

SettlementOffered

Bool

True if a settlement was offered on this account, false otherwise

SettlementAmount

Decimal

The amount of the settlement that was offered on this account.

MaxSettlementPayments

integer

The maximum number of payments allowed for a settlement on this account.

MaxSettlementDate

Date

The last date a payment can be schedule to complete a settlement arrangement.

ClientID

String

A unique client ID used to identify the client in the integrated system

InternalStatus

String

The status of the account. This is an internal status and will NOT be shown to the user.

StatusOfAccount

String

The status of the account that can be displayed to the user. If not specified this will not be shown. This is visible to the user. Do NOT use internal statuses. 

OriginalAccountNumber

String

The account number that was originally assigned to the account.

OriginalCreditor

String

The name of the original creditor

ClientName

String

The name of the client.

CollectorNameShort

String

The name of the collector assigned to this account. This is a shorter name used if you want to abbreviate or use a desk.

CollectorNameLong

String

The name of the collector assigned to this account.

CollectorPhone

String

The phone number to reach the collector.

CustomAccountFields

Other

 

PaymentAmt1-
 PaymentAmt100

Decimal

Amount of the payment (see payment fields)

PaymentDate1-
 PaymentntDate100

Date

Date of the payment (see payment fields)

PaymentDesc1-

PaymentDesc100

String

Description of the payment (max 50 characters) (see payment fields)

PostDateAmt1-

PostDateAmt100

Decimal

Amount of the postdate (see postdate fields)

PostDateDate1-

PostDateDate100

Date

Date of the postdate (see postdate fields)

PostDateDesc1-

PostDateDesc100

String

Description of the postdate (max 50 characters) (see postdate fields)

SettlementACHAllowed

Bool

Allow ACH for Settlements. Only applicable when there is a settlement offer. This field may be null. This field is unlike standard boolean fields as it will not default to false if left null. Instead, it will use the system default setting.

SettlementCreditCardAllowed

 

Allow Credit Cards for Settlements. Only applicable when there is a settlement offer. This field may be null. This field is unlike standard boolean fields as it will not default to false if left null. Instead, it will use the system default setting.

SettlementDebitCardAllowed

 

Allow Debit Cards for Settlements. Only applicable when there is a settlement offer. This field may be null. This field is unlike standard boolean fields as it will not default to false if left null. Instead, it will use the system default setting.

*CellPhone
This field can be used for texting features.

NOTE: this field is formatted as a custom field and has the asterisk prefix. It is essentially a "reserved" custom field that is treated as a regular field. There are internal/backwards compatibility reasons why this field is named differently.

Accepted formats are:
  • 9999999999
    or
  • 999-999-9999

 

Additional Fields

The fields below are not data fields for the account. Instead, they are action fields that can be included with an account. They will cause an action to occur after the import of the file.

Name

Type

Description

EmailTemplateName

String

This field may contain the internal template name of one of your email templates. When this field contains a value, an email batch will be created after the file is imported. This field and any values in it are optional. You can add a value on some records and not on others. Any value that is included must be a valid email template name.

 

Common Questions

What is the format of the data file?

The format details of the CSV file are listed below this section. The format has standard fields and allows for unlimited custom fields.

How often should I upload the data file?

We recommend uploading a new data file once per day. This ensures that the consumer information is no more than one (1) day old, provided up-to-date information to Consumers.

Do you support real-time/live data access instead of having day old data?

Yes – advanced setups are available that allow your data to be live on the website. These setups require integration software and setup by your Agency. This setup has advantages but requires that you have the IT personnel to install/manage/troubleshoot. There is also an additional fee for this setup.

How do I upload the file?

Your agency will have access to an SFTP site. You may use any tool that supports SFTP to upload your file, or you may automate a process that uploads the file on a regular basis.

How long does it take to import my data?

Our systems run 24/7 and look for any new data files. Most data files are processed within one (1) hour of uploading; larger files may take more time. These processes seamlessly run behind the scenes, making the solution full accessible to all users and Consumers while the data is imported.

Can we import other types of files?

If you are unable to produce the standard data import files, our team can work with you to create a custom import that will read the format you are able to produce and import it. Additional technical programming costs apply.