Articles in this section

Import files to AP Hub

Use this page to prepare, upload, and track import files in Tipalti for payees, GL accounts, tax codes, and custom field values.

Import center

Use the "Import center" subtab to add new payees or block/ suspend payees in Tipalti. For each action, you need to prepare the relevant CSV file, upload it to the Tipalti Hub and download the result file, which lets you know the status of each import.

Add new payees

Required user roles Payer Administration & Add Payee

Add new payees to Tipalti. You cannot use this method to edit existing payees.

Prepare payees list file

Prepare a CSV file of new payees you want added to Tipalti. Each row in the file details a different payee. Click the image below to download a sample of the CSV file structure. You can clear all data in the file and enter your own data for upload. The maximum file size allowed is 20 MB (~100,000 payees).

Payees List - sample file

File structure

Fields are not case sensitive.

Field

Description

Limitation

Mandatory?

Data type
Idap
  • Unique payee identifier (the payee ID)
  • If this field is left empty, a new payee will be created with an auto-generated ID.
  • By default, the type of payee is set automatically to "Company". This information can be changed directly on the payee record.
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
  • The default delimiter in the file is a comma (,)
 Mandatory string
Email
  • Payee email address
  • If the email address already exists in Tipalti for a different payee, the new payee will be created without an email address.
  • Max. length = 200
  • Valid email format (e.g., user@domain.com)
 Mandatory string
FirstName Payee first name Payee first name Optional string
MiddleName Payee middle name Payee middle name Optional string
LastName Payee last name Payee last name Optional string
CompanyName Payee company name Payee company name Optional string
PreferredEntity
  • The name of the payer entity to link to the payee
  • Only add this column to the file if the payer has multiple entities defined in Tipalti.
  • If the entity is not specified, the payer's default entity will be linked to the payee. This information can be changed on the payee record.
  • Max. length = 100
  • Alphanumeric characters only
 Optional string
ErpPayeeCurrency The payer's QuickBooks Online vendor currency
  • Applies only to payers using QuickBooks Online
  • Multi-currency must be enabled in QuickBooks Online
  • Once a value is set, it cannot be changed
  • Length = 3 (per ISO 4217)
 Optional string

Upload file

To import the payees list file to the Tipalti Hub:

  1. Go to Administration > Import center. A list of previously uploaded files displays.
  2. At the top right of the screen, click "+ Import records", then select "Payees list".
  3. Select the relevant file and click "Open".
  4. If you have payer email notifications enabled for when payee details change, a dialog appears advising you to disable emails before the file is uploaded. If you don't disable emails, the payer will receive an email for each payee listed in the CSV file. Do one of the following.
    • Don't disable emails.
      • In the dialog, click "Don't disable emails".
      • Go to step 5.
    • Disable emails.
      • Close the dialog.
      • Beside the Import center subtab, click Communication.
      • On the "Email notifications" screen, toggle the last setting "Off", as shown below.
      • Click the check mark to confirm.
      • Go back to step 1.
  5. The file is validated for errors. Do one of the following.
    • If there are no errors or warnings, a "Payees import results" dialog displays the results of the import. You can download a summary of the results by clicking . Click "Import records" to update the Tipalti Hub.
    • If there are warnings, the "File manager" box appears in the top right of the screen. Click View icon to display the results. You can download a summary of the results by clicking the "Download warnings" link or . Do one of the following.
      • Correct the issues and re-upload the file.
      • Ignore the warnings and proceed to update the Tipalti Hub by selecting "Import records".
    • If upload fails, the "File manager" box appears in the top right of the screen. Click View icon to display the results. You can click CSV icon to download a log of the errors.
      • Click "Cancel upload".

      • Correct the errors and upload the file again.

        If the payer is using the Supplier Hub to onboard payees, then by default, the "Invite payees to suppliers Hub" check box is selected in the "Import results" dialog. Upon upload, the email addresses listed in the file receive an invite to register in the Hub.
  6. If you disabled emails in step 4b above, then re-enable emails.

Updating records can take a while, depending on the number of records.

  • If you are logged out of the Tipalti Hub during validation, you will receive an email when validation is complete.
  • If you are logged out when the update completes, you will see the upload result upon logging back into the Tipalti Hub.

Output: Import result file

The import result CSV file lets you know whether the new payees in the file that you uploaded will be created in Tipalti, or if there are errors that need correcting. Download this file by clicking Download icon at the end of the imported file row.

File structure

The result file includes all fields in the uploaded payees list file plus the following fields.

Field

Description

Limitation
Record type Indicates whether the record will be created as a new payee

Valid values:

  • OK
  • Error
Record status

The status of the import:

  • OK - The record will be imported with no errors or warnings.
  • If there are warnings, the relevant messages display.

Valid values:

  • OK
  • "Warning messages"
Block/ suspend payees

Required user roles Payer Administration & Risk Management

Block or suspend payees in Tipalti.

Prepare blocked/ suspended payees file

Prepare a CSV file of payees you want blocked or suspended in Tipalti. Each row in the file details a different payee. Click the image below to download a sample of the CSV file structure. You can clear all data in the file and enter your own data for upload. The maximum file size allowed is 20 MB.

Blocked / Suspended Payees sample CSV file

File structure

Fields are not case sensitive.

Field

Description

Limitation

Mandatory?
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
 Mandatory
Status The status of the payee

Valid values::

  • Suspended
  • Blocked
 Mandatory
BlockingReason The reason the payee is blocked or suspended Supported only for "Blocked" and "Suspended" statuses Mandatory

Upload file

To import a blocked/ suspended payees file to the Tipalti Hub:

  1. Go to Administration > Import center. You can see the list of previously uploaded files.
  2. At the top right of the screen, click "+ Import records", then select "Blocked or suspended payees".
  3. Select the relevant file and click "Open".
  4. The file is validated for errors. Do one of the following.
    • If there are no errors or warnings, a "Blocked and suspended payees import results" dialog displays the results of the import. You can download a summary of the results by clicking . Click "Import records" to update the Tipalti Hub.
      If there is at least one payee that is blocked/ suspended in Tipalti but is not included in the uploaded file, the following message displays: "Reset the existing blocked and suspended payees list with this list."
      • To overwrite the list in the Tipalti Hub, select the box beside this message. This action will also update the status to "Active" for any blocked or suspended payee in Tipalti that is not included in the uploaded file.
      • To download the list of payees that will be updated, click the "Download list" link.
    • If there are warnings, an "Upload" dialog appears in the bottom right of the screen. Click View icon to display the results. You can download a summary of the results by clicking the "Download warnings" link or . Do one of the following.
      • Correct the issues and re-upload the file.
      • Ignore the warnings and proceed to update the Tipalti Hub by selecting "Import records".
    • If upload fails, an "Upload" dialog appears in the bottom right of the screen. Click View icon to display the results. You can click CSV icon to download a log of the exceptions.
      • Click "Cancel upload".
      • Correct the errors and upload the file again.

Updating records can take a while, depending on the number of records.

  • If you are logged out of the Tipalti Hub during validation, you will receive an email when validation is complete.
  • If you are logged out when the update completes, you will see the upload result upon logging back into the Tipalti Hub.

Output: Import result file

The import result CSV file lets you know whether the payees in the file that you uploaded will be blocked or suspended in Tipalti, or if there are errors that need correcting. Download this file by clicking Download icon at the end of the imported file row.

File structure

The result file includes all fields in the uploaded blocked/ suspended payees file plus the following fields.

Field

Description

Limitation
Record status

The status of the import:

  • OK - The record will be imported with no errors or warnings.
  • Warning - The record will be imported, but with warnings.
  • Error - The record will not be imported.

Valid values:

  • OK
  • Warning
  • Error
Description
  • If the "Record status" is OK, the change to the payee status displays (e.g., Payee Blocked, Payee Suspended).
  • If there are warnings/ errors, the relevant messages display.

Valid values:

  • Payee Blocked
  • Payee Suspended
  • "Warning/ error messages"

Import GL accounts, tax codes & custom fields

On the "Integrations" tab, you can import GL accounts, tax codes, and custom field values.

File import screen

Prepare import files

Required user role Payer Administration

To import your files, you need to prepare a CSV file and import it to the Tipalti Hub. Select a record below to see the fields included in each import template.

Prepare GL account list file

Required user role Payer Administration

Prepare a CSV file of GL accounts you want added to Tipalti. Each row in the file details a different account.

The following table lists the fields in the GL accounts template. All values input to the template are case sensitive. The maximum file size allowed is 20 MB.

Field Display Name isMandatory? Description Field data type Level Value Display Names
Category No

The category of the GL account (not case sensitive).

Only accounts set as "Expense" (and active AP accounts set as "Other") are available on all bill records/ filters

 List Header Other, Expense
Currency No The currency of the GL account String Header  
Description No A description of the GL account String Header  
Entity name No

List of payer entities for which each GL account should apply.

A GL account can be associated with more than one entity, entity names should be separated by ";"

To apply the GL account to all payer entities, use '[]'

 String Header  
External ID Yes An ID that uniquely identifies the GL account in the accounting system/ ERP String Header  
MiscBox1099 No

The number of the corresponding box on the 1099-MISC form.

If the field is left empty (NULL), the account will be considered "unmapped"

 List Header
  • nec1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 12
  • 13
  • 14
  • 15A
  • 15B
  • 16
  • 17
  • 18
  • 1
  • Non applicable
  • 11
  • nec2
Name Yes The name of the GL account String Header  
Number No The number of the GL account String Header  
Sync type No Whether to update or close the GL account. GL accounts that are currently active (i.e., assigned to outstanding unpaid bills) cannot be closed List Header Close, Create / Update
Type No The type of GL account List Header
  • Long Term Liability
  • Other assets
  • Fixed assets
  • Other current assets
  • Accounts receivable A_R
  • Expenses
  • Income statement account
  • Balance sheet account
  • Receivable account
  • Unbilled Receivable
  • Deferred Expense
  • Deferred
  • Revenue
  • Other Expense
  • Other Income
  • Cost of Goods Sold
  • Income
  • Equity
  • Expense
  • Accounts payable
  • Bank
  • Credit card
  • Accounts Receivable
  • Other Current Asset
  • Fixed Asset
  • Other Asset
  • Other Current Liability
  • Other current liabilities
  • Long term liabilities
  • Liability
  • Liabilities
  • Asset
  • Assets
  • Revenue
  • Other

Prepare custom field values file

The following table lists the fields in the custom field template. All values input to the template are case sensitive. The maximum file size allowed is 20 MB.

FIELD name

DESCRIPTION

limitation

Mandatory?

data type
Value The list item name you want displayed for payers (in the Tipalti Hub and reports) and payees (onboarding process)
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
 Mandatory string
Code The unique ID of the list item
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
 Mandatory string
Status
  • Indicates the status of the custom field value: Active or Inactive
  • If this field is excluded on the file, the value is considered "Active".
  • Inactive values cannot be used when submitting new bills.
  • Custom field values on approved bills do not change status if, in the future, the value is made inactive/ active
 If empty, it is set to "Active"   boolean

Prepare tax codes file

The following table lists the fields in the tax codes template. All values input to the template are case sensitive. The maximum file size allowed is 20 MB.

FIELD name

DESCRIPTION

Mandatory?

data type
External ID The tax code identifier in your accounting system/ ERP Mandatory string
Name
  • The name of the tax code (e.g., VAT-UK)
  • If you change the name of an existing tax code, it is changed on all bills linked to the tax code. Bill status is not affected.
 Mandatory string
Active
  • Indicates if the tax code is active or inactive
  • If an active tax code becomes inactive:
    • It is removed from bills pending internal or payee approval/ invoice. The bills are sent back to AP so that a new tax code can be assigned.
    • Bills in a "PendingPayment" status or later remain unaffected.
    • It is removed from bills in any other status. Screen reader support enabled.
 Mandatory boolean
Rate
  • The rate of the tax code (e.g., 20.0 for 20% tax)
  • If the rate of an existing tax code is changed:
    • Bills in a status earlier than "Pending Payment" are updated.
    • Bills in status "Pending Payment" or later remain unaffected.
 Mandatory decimal
Payer entities
  • List of payer entity names, as used in the Tipalti Hub—e.g., Payer entity 1, Payer entity 2, Payer entity 3, Payer entity 4.
  • To apply the tax code to all payer entities, this field should remain empty.
  • If an entity linked to the tax code has been updated and is no longer available for existing bills, the bills are treated the same as when tax codes become inactive (refer to the description for the "Active" element above).
 Optional string
Manually import files

Required user role Payer Administration

To manually import GL accounts:

  1. Go to Integrations > File import and click "Import" to open the "Data import - File upload" dialog.
    File import screen
  2. From the dropdown, select the record that you want to import.
  3. Click "Select", choose the relevant file, and click "Open". Upon import, the system validates your file. 
    Only CSV files are supported (max. file size is 20 MB).
  4. If validation is successful, click "Next" to complete the import.
    Data import - File upload dialog
  5. View the imported file status in the "File import" table.
    • Successful icon indicates that the file imported successfully
    • Failed icon indicates that the file failed to import
    • Partial import icon indicates that the file partially imported successfully
  6. At the end of the row, hover over Actions menu and select to either download the original or the error file.
    File import action menu

The following table describes the columns on the "File import" screen.

Column

Description
Date Date of the file import was completed
Record type Type of record selected for import
File name Name of imported file
Status

Successful icon Files that imported successfully

Failed icon Files that failed to import

Partial import icon Files that partially imported
Total records Number of records in the imported file
New records Number of new records that have been created by the import
Updated records Number of records that have been updated by the import
Alerts Number of records in the original file that failed to import
Requested by
  • If standard sync, email address of the user who imported the file
  • If auto-sync, then the text "Auto-sync" displays
Actions menu Action menu to download the original imported file or errors file