Function: GetPayeeInvoicesListDetails

The GetPayeeInvoicesListDetails function returns invoice details for a list of payee invoices.

The following is a sample SOAP 1.2 request and response. In the request, you need to replace the data types in yellow with actual values.

SOAP 1.2: Request

POST /v3/payerfunctions.asmx HTTP/1.1

Host: api.tipalti.com

Content­Type: application/soap+xml; charset=utf­8

Content-Length: length

<?xml version="1.0" encoding="utf­8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-­instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap­envelope">

<soap12:Body>

<GetPayeeInvoicesListDetails xmlns="http://Tipalti.org/">

<payerName>​string​</payerName>

<timestamp>​double​</timestamp>

<key>​string​</key>

<invoicesRefCodes>

<string>​string​</string>

<string>​string​</string>

</invoicesRefCodes>

</GetPayeeInvoicesListDetails>

</soap12:Body>

</soap12:Envelope>

SOAP 1.2: Response

HTTP/1.1 200 OK

Content­Type: application/soap+xml; charset=utf­8

Content­Length: length

<?xml version="1.0" encoding="utf­8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-­instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap­envelope">

<soap12:Body>

<GetPayeeInvoicesListDetailsResponse xmlns="http://Tipalti.org/">

<GetPayeeInvoicesListDetailsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<InvoiceErrors>

<TipaltiInvoiceItemError>

<ErrorMessage>string​</ErrorMessage>

<ErrorCode>string​</ErrorCode>

<InvoiceRefCode>​string​</InvoiceRefCode>

</TipaltiInvoiceItemError>

<TipaltiInvoiceItemError>

<ErrorMessage>​string</ErrorMessage>

<ErrorCode>​string​</ErrorCode>

<InvoiceRefCode>​string​</InvoiceRefCode>

</TipaltiInvoiceItemError>

</InvoiceErrors>

<Invoices>

<TipaltiInvoiceItem>

<Idap>​string​</Idap>

<InvoiceRefCode>​string​</InvoiceRefCode>

<InvoiceDate>​dateTime​</InvoiceDate>

<InvoiceDueDate>​dateTime​</InvoiceDueDate>

<Description>​string​</Description>

<CanApprove>​boolean</CanApprove>

<InvoiceInternalNotes>​string​</InvoiceInternalNotes>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>​boolean​</IsPaidManually>

<IncomeType>​string​</IncomeType>

<InvoiceLines>

<InvoiceLine>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<GLAccount>

<TipaltiGLAccount>

<Name>string</Name>

<Number>string</Number>

<ExternalId>string</ExternalId>

<Description>string</Description>

<MiscBox1099>string</MiscBox1099>

<Type>string</Type>

<Currency>string</Currency>

</TipaltiGLAccount>

</GLAccount>

<LineType>string</LineType>

<LineExternalMetadata>string</LineExternalMetadata>

<Quantity>decimal</Quantity>

<BillLineID>string</BillLineID>

<TaxCodeExternalId>string</TaxCodeExternalId>

<TaxAmount>decimal</TaxAmount>

<RelatedPurchaseOrders>

<TipaltiRelatedPurchaseOrder>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<ItemNumber>string</ItemNumber>

<Quantity>decimal</Quantity>

<Amount>decimal</Amount>

<ExternalLineId>string</ExternalLineId>

<ItemExternalId>string</ItemExternalId>

<PoLineGlAccountExternalId>string</PoLineGlAccountExternalId>

</TipaltiRelatedPurchaseOrder>

</RelatedPurchaseOrders>

</InvoiceLine>

</InvoiceLines>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Approvers>

<TipaltiInvoiceApprover>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<ApprovalDate>dateTime</ApprovalDate>

<VendorCredits>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

</TipaltiInvoiceItem>

<TipaltiInvoiceItem>

<Idap>​string​</Idap>

<InvoiceRefCode>​string​</InvoiceRefCode>

<InvoiceDate>​dateTime​</InvoiceDate>

<InvoiceDueDate>​dateTime​</InvoiceDueDate>

<Description>​string​</Description>

<CanApprove>​boolean</CanApprove>

<InvoiceInternalNotes>​string​</InvoiceInternalNotes>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>​boolean​</IsPaidManually>

<IncomeType>​string​</IncomeType>

<InvoiceLines>

<InvoiceLine>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<GLAccount>

<TipaltiGLAccount>

<Name>string</Name>

<Number>string</Number>

<ExternalId>string</ExternalId>

<Description>string</Description>

<MiscBox1099>string</MiscBox1099>

<Type>string</Type>

<Currency>string</Currency>

</TipaltiGLAccount>

</GLAccount>

<LineType>string</LineType>

<LineExternalMetadata>string</LineExternalMetadata>

<Quantity>decimal</Quantity>

<BillLineID>string</BillLineID>

<TaxCodeExternalId>string</TaxCodeExternalId>

<TaxAmount>decimal</TaxAmount>

<RelatedPurchaseOrders>

<TipaltiRelatedPurchaseOrder>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<ItemNumber>string</ItemNumber>

<Quantity>decimal</Quantity>

<Amount>decimal</Amount>

<ExternalLineId>string</ExternalLineId>

<ItemExternalId>string</ItemExternalId>

<PoLineGlAccountExternalId>string</PoLineGlAccountExternalId>

</TipaltiRelatedPurchaseOrder>

</RelatedPurchaseOrders>

</InvoiceLine>

</InvoiceLines>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Approvers>

<TipaltiInvoiceApprover>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<ApprovalDate>dateTime</ApprovalDate>

<VendorCredits>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

</TipaltiInvoiceItem>

</Invoices>

</GetPayeeInvoicesListDetailsResult>

</GetPayeeInvoicesListDetailsResponse>

</soap12:Body>

</soap12:Envelope>

Request parameters

element

description

limitation

Mandatory?

data type
payerName The name of the payer, as assigned by Tipalti
  • Max. length = 50
  • Value is case sensitive
 Mandatory string
timestamp

Current time (UTC) when the request is sent

 Unix time Mandatory double
key Encryption key   Mandatory string
invoicesRefCodes List of invoice reference codes Max. request limit = 200 refcodes Mandatory Array of string

string

element

description

limitation

data type
string The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string

Response parameters

element

description

data type
GetPayeeInvoicesList
DetailsResult		 Contains the response parameters TipaltiGetPayeeInvoicesList
DetailsResponse (extension of type TipaltiResponse)

TipaltiGetPayeeInvoicesListDetailsResponse

element

description

Limitation

data type
errorMessage A description of the error See API error codes. string
errorCode The status of the error See API error codes. string
b If the return code is Boolean, this parameter will carry the value.   boolean
i If the return code is integer, this parameter will carry the value.   integer
d If the return code is double, this parameter will carry the value.   double
s If the return code is string, this parameter will carry the value.   string
InvoiceErrors
  • Array of invoice item errors
  • Each invoice item error is of type TipaltiInvoiceItemError.
  Array of TipaltiInvoiceItemError
Invoices
  • Array of invoice items
  • Each invoice item is of type TipaltiInvoiceItem.
Max. records returned = 200 Array of TipaltiInvoiceItem
TipaltiInvoiceItemError

The error 1011 "InvoiceRefCodeUnknown" is returned by the GetPayeeInvoicesListDetails Endpoint for any invoices that currently don't have any bill lines created for them (e.g., an invoice created in the Tipalti Hub before it was saved by the user)

element

description

LIMITATION

data type
ErrorMessage A description of the error See API error codes. string
ErrorCode The status of the error See API error codes. string
InvoiceRefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
TipaltiInvoiceItem

Element

Description

Limitation

Data Type
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
 string
InvoiceRefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
InvoiceDate Invoice value date (estimated date and time the payee receives the funds) YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section dateTime
InvoiceDueDate The date and time the invoice is due to be paid YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section dateTime
Description A description of the invoice Max. length = 256 string
CanApprove Indicates whether or not the payee is able to approve the invoice   boolean
InvoiceInternalNotes Notes that are not displayed to the payee
  • Max. length = 256
  • Default = null
 string
CustomFields If custom fields have been defined for the bill/ invoice entity, the field name is the display name and the value is what was defined on the bill.
  • Default = null
  • Max. length = 140 for "free text" entries
 Array of KeyValuePair
IsPaidManually If TRUE, the invoice is marked as paid manually   boolean
IncomeType If the Tax Withholding module is enabled and there are multiple income types that can be associated with the payment, then you must enter the income type per payment.
  • See Income types.
  • Default = null
 string
InvoiceLines
  • List of invoice lines
  • Each invoice line is of type InvoiceLine.
   Array of InvoiceLine
InvoiceStatus The status of the bill

Valid values:

  • Deleted
  • Disputed
  • Paid
  • PartiallyPaid
  • PendingApAction
  • PendingApproval
  • PendingApReview
  • PendingPayeeApproval
  • PendingPayeeInvoice
  • PendingPayment
  • ScheduledForPayment
  • SubmittedForPayment
string
Currency The currency of the invoice Length = 3 (per ISO 4217) string
Approvers List of bill approvers   Array of TipaltiInvoiceApprover
InvoiceNumber The number of the invoice Max. length = 256 string
ApprovalDate Date and time the invoice was approved for payment YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section dateTime
VendorCredits List of vendor credits applied to the payment

Only returned after bills have been paid using one or more vendor credits

 Array of TipaltiVendorCredit
InvoiceLine

element

description

limitation

data type
Currency The currency of the invoice Length = 3 (per ISO 4217) string
Amount Invoice line amount   double
Description Description of the invoice line Max. length = 256 string
InvoiceInternalNotes Notes that are not displayed to the payee
  • Max. length = 256
  • Default = null
 string
EWalletMessage
  • A message to attach to the payment
  • This message is sent to providers and appears on payee bank statements.
  • If no value is provided, the InvoiceRefCode is used.
  • Max. length = 160
  • Default = null
 string
BankingMessage
  • A message to attach to the payment
  • This message is sent to providers and appears on payee bank statements.
  • If a value is not provided, the EWalletMessage is used.
  • Max. length = 160
  • Default = null
  • Supported for:
    • ACH
    • Check
    • Global ACH/Local bank transfer
    • Wire transfer
string
CustomFields

If custom fields have been defined for the bill/ invoice line entity, the field name is the display name and the value is what was defined on the bill line.
  • Default = null
  • Max. length = 140 for "free text" entries
 Array of KeyValue
Pair
GLAccount GL account linked to the invoice line   TipaltiGL
Account
LineType

The type of invoice line:

  • AccountBased - the line is based on the
    GL account linked to the invoice line
  • ItemBased - the line is based on an item in the invoice
 Valid values:
  • AccountBased
  • ItemBased
 string
LineExternalMetadata
  • The item ID for the item-based line
  • Only applies if LineType = ItemBased
   string
Quantity
  • The number of items for the item-based line
  • Only applies if LineType = ItemBased
   decimal
BillLineID
  • The bill line identifier
  • If there is no line ID, the system creates one automatically.
   string
TaxCodeExternalId The type of tax code and its rate—e.g., VAT-UK (20%)   string
TaxAmount
  • The amount of tax for the line
  • A negative number (for vendor credit) is allowed
   decimal
RelatedPurchaseOrders
  • List of purchase orders related to the invoice
  • Each purchase order is of type TipaltiRelatedPurchaseOrder
   Array of TipaltiRelated
PurchaseOrder
TipaltiGLAccount

element

Description

Limitation

Data Type
Name The name of the GL account Max. length = 450 string
Number
  • The number of the GL account
  • GL account numbers must be unique.
 Max. length = 450 string
ExternalId An ID that uniquely identifies the GL account (e.g., in NetSuite, it is the "Internal ID") Max. length = 100 string
Description A description of the GL account Max. length = 450 string
MiscBox1099
  • The number of the corresponding box on the 1099-MISC form
  • If the field is left empty (NULL), the account will be considered "unmapped".

Valid values for expense accounts:

  • Non applicable
  • 1
  • 2
  • 3
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • nec1
  • nec2

Note: The values above apply to the "New IRS format (2020 and onwards)". Click here to see the "Old IRS format (pre-2020)".

 string
Type The type of GL account

Valid values:

  • Expense (default)
  • Accounts payable
  • Bank
  • Credit card
 string
Currency The currency of the GL account Length = 3 (per ISO 4217) Optional
TipaltiRelatedPurchaseOrder

Element

Description

Data type
PurchaseOrderNumber An identifier for the purchase order string
ItemNumber Code for the purchase order line string
Quantity Quantity of the purchase order line decimal
Amount Amount of the purchase order line decimal
ExternalLineId The identifier of the purchase order line in your accounting system string
PoLineGlAccountExternalId The GL account of the PO line linked to the invoice line string
KeyValuePair

Element

description

data type
Key Name of field string
Value Value of field string
TipaltiInvoiceApprover

element

Description

Data Type
Name Name of bill approver string
Email Email address of bill approver string
Order
  • The order of the approver in a sequence of approvers
  • If no value is included, the system will use the order of appearance in the array.
 integer
TipaltiVendorCredit

element

Description

Data Type
RefCode The reference code for the vendor credit string
AppliedAmount The amount of vendor credit applied to the bill double