Function: GetPayeeInvoiceList

The GetPayeeInvoiceList function returns a list of unpaid invoices/ bills for a specific payee. Use the IncludePaidInvoices parameter to include or exclude paid invoices/ bills.

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 /v8/payeefunctions.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>

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

<payerName>string</payerName>

<idap>string</idap>

<timestamp>double</timestamp>

<key>string</key>

<includePaidInvoices>boolean</includePaidInvoices>

</GetPayeeInvoiceList>

</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>

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

<GetPayeeInvoiceListResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<PayeeInvoices>

<PayeeInvoiceStatus>

<RefCode>string</RefCode>

<ApprovalStatus>string</ApprovalStatus>

<PaymentStatus>string</PaymentStatus>

<TotalAmount>double</TotalAmount>

<PaidAmount>double</PaidAmount>

<UnpaidAmount>double</UnpaidAmount>

<InvoiceNumber>string</InvoiceNumber>

<Approvers>

<TipaltiInvoiceApprover>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceStatus>string</InvoiceStatus>

<ApprovalDate>dateTime</ApprovalDate>

<VendorCredits>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

<ScheduledAmount>double</ScheduledAmount>

</PayeeInvoiceStatus>

<PayeeInvoiceStatus>

<RefCode>string</RefCode>

<ApprovalStatus>string</ApprovalStatus>

<PaymentStatus>string</PaymentStatus>

<TotalAmount>double</TotalAmount>

<PaidAmount>double</PaidAmount>

<UnpaidAmount>double</UnpaidAmount>

<InvoiceNumber>string</InvoiceNumber>

<Approvers>

<TipaltiInvoiceApprover>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceStatus>string</InvoiceStatus>

<ApprovalDate>dateTime</ApprovalDate>

<VendorCredits>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

<ScheduledAmount>double</ScheduledAmount>

</PayeeInvoiceStatus>

</PayeeInvoices>

<TotalScheduledForPayment>double</TotalScheduledForPayment>

</GetPayeeInvoiceListResult>

</GetPayeeInvoiceListResponse>

</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
idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
Mandatory string
timestamp

Current time (UTC) when the request is sent

 Unix time Mandatory double
key Encryption key   Mandatory string
includePaidInvoices If TRUE, paid invoices/ bills are included on the returned list   Mandatory boolean

Response parameters

element

description

data type
GetPayeeInvoiceListResult Contains the response parameters TipaltiPayeeInvoiceStatusResponse

TipaltiPayeeInvoiceStatusResponse

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
PayeeInvoices
  • List of payee invoices/ bills
  • Each invoice/ bill is of type PayeeInvoiceStatus
 Only displays after invoices/ bills have been reviewed Array of PayeeInvoiceStatus
TotalScheduledForPayment The total scheduled amount for all invoices/ bills Only displays after payer has approved the payment group (if approval is required) double
PayeeInvoiceStatus

element

description

limitation

data type
RefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
ApprovalStatus
  • Invoice approval status
  • Approved—if bill status is "Pending payment", "Paid" or "Submitted for payment"
  • Declined— if bill status is "Deleted" or "Disputed"

Valid values:

  • None
  • Approved
  • Declined
string
PaymentStatus Payment status of the invoice

Valid values:

  • Unpaid
  • Paid
  • PartiallyPaid
string
TotalAmount Total amount of the invoice   double
PaidAmount Amount already paid for the invoice   double
UnpaidAmount Unpaid amount of the invoice   double
InvoiceNumber The number of the invoice Max. length = 256 string
Approvers List of bill approvers   Array of TipaltiInvoiceApprover
InvoiceStatus The status of the bill

Valid values:

  • Deleted
  • Disputed
  • Paid
  • PartiallyPaid
  • PendingApAction
  • PendingApproval
  • PendingApReview
  • PendingPayeeApproval
  • PendingPayeeInvoice
  • PendingPayment
  • ScheduledForPayment
  • SubmittedForPayment
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
ScheduledAmount The amount of the invoice/ bill scheduled for payment at a later date Only displays after payer has approved the payment group (if approval is required) double
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