--- title: Tipalti API Integration on Truto slug: tipalti category: Accounting canonical: "https://truto.one/integrations/detail/tipalti/" --- # Tipalti API Integration on Truto **Category:** Accounting **Status:** Beta ## MCP-ready AI tools Truto exposes 36 tools for Tipalti that AI agents can call directly. - **list_all_tipalti_custom_fields** — List Tipalti custom fields according to search/filtering criteria; if no filter is specified, all custom fields are returned. Returns each custom field's id, externalId, name, description, resources, valueType, isActive, and attributes. - **get_single_tipalti_custom_field_by_id** — Get a specific Tipalti custom field by id. Returns the full custom field object including id, externalId, name, description, resources, valueType, isActive, and attributes. Required: id. - **list_all_tipalti_gl_accounts** — List Tipalti GL accounts, optionally filtered by id, externalId, isClosed, or category; all accounts are returned when no filter is given. Returns for each account: id, externalId, name, number, currency, isClosed, report1099Type, category, erpAccountType, and payerEntityIds. - **get_single_tipalti_gl_account_by_id** — Get a single Tipalti GL account by id. Returns the full account object including id, externalId, name, number, currency, isClosed, report1099Type, category, erpAccountType, and payerEntityIds. Required: id. - **create_a_tipalti_invoice_batch** — Create a Tipalti invoice batch to initiate asynchronous invoice creation. Returns a batch header with id, status, timeCreated, and operationType. Requires batchHeader and items; each invoice requires batchItemId, refCode, subject, invoiceDate, currency, payeeId, payerEntityId, apAccountId, customFieldValues, and lines. Max 200 invoices per batch, 100 lines per invoice. - **get_single_tipalti_invoice_batch_by_id** — Get a Tipalti invoice batch upload summary by id. Returns the batch's processing status in batchHeader (status, timeCreated, timeCompleted, successfulItemsCount, failedItemsCount), the per-invoice results in items (batchItemId, id, status), and batch-level errors in batchErrors. Required: id. - **list_all_tipalti_invoices** — List Tipalti invoices according to search/filtering criteria; all invoices are returned when no filter is specified. Returns: id, invoiceNumber, subject, payeeVatNumber, invoiceDate, dueDate, netAmount, taxAmount, totalAmount, paidAmount, unpaidAmount, payeeId, creationDate, updatedDate, description, refCode, status, payerEntityId, apAccountId, incomeType, customFieldValues, lines, links. - **get_single_tipalti_invoice_by_id** — Get a Tipalti invoice by id. Returns the full invoice object including id, invoiceNumber, refCode, status, amount details, custom field values, invoice lines, and related resource links. Required: id. - **create_a_tipalti_payee** — Create a new payee in Tipalti from the provided details. Returns the created payee including its id, refCode, status, entityType, contactInformation, paymentMethod, and customFieldValues. Requires refCode (the payee's unique reference code). When entityType is INDIVIDUAL, contactInformation.firstName and lastName are required; when COMPANY, contactInformation.companyName is required. - **list_all_tipalti_payees** — List payees in Tipalti according to search/filtering criteria; if no filter is given, all payees are returned. Returns payee records including id, refCode, status, isPayable, contactInformation, and paymentMethod. Filter by id, refCode, status, isAccountClosed, contact fields, or lastChangeDateTimeUTC. - **get_single_tipalti_payee_by_id** — Get a single payee in Tipalti by its id. Returns the full payee record including id, refCode, status, entityType, isPayable, contactInformation, paymentMethod, and customFieldValues. Required: id. - **update_a_tipalti_payee_by_id** — Update a payee in Tipalti by id. Omitted parameters are left unchanged; null or empty values delete the field, except entityType, status, contactInformation, and customFieldValues, which can't be null or empty. Returns the updated payee including id, refCode, status, isPayable, and contactInformation. Required: id. - **tipalti_payees_bulk_update** — Update a payee's payment method in Tipalti by id. Returns the updated method including paymentMethodType, currency, and paymentMethodInformation. Required: payee_id, paymentMethodType, and paymentMethodInformation. PayPal and check methods apply to US payees only, and currency can't be changed via the API. - **list_all_tipalti_payer_entities** — List Tipalti payer entities, optionally filtered by id, entityName, legalName, isDefault, or brandName. Returns: id, entityName, legalName, isDefault, brandName, externalId, incomeTypes. All payer entities are returned when no filter is specified. - **get_single_tipalti_payer_entity_by_id** — Get a single Tipalti payer entity by id. Returns: id, entityName, legalName, isDefault, brandName, externalId, incomeTypes. Required: id. - **create_a_tipalti_payment_batch** — Create a payment batch in Tipalti that joins a list of payment instructions into a single request. Returns: id. Required: paymentInstructions — each instruction requires payeeId, amountSubmitted, and refCode. Batches with more than 5,000 instructions return an error. - **get_single_tipalti_payment_batch_by_id** — Get the upload summary for a Tipalti payment batch by id, including its creation status. Returns: id, status, name, submissionDateTime, isValidForSubmission, fundsProvidersSummary, exchangeRateCautionBufferPercentage, paymentsBatchErrors. Required: id. Once the batch is created, verify each individual payment instruction's status via the payment instructions endpoint. - **create_a_tipalti_payment_term** — Create a payment term in Tipalti with an ERP external ID, a name, and the number of business days added to the invoice date to determine the due date. Returns: id, externalId, name, days, isDefault. Requires externalId, name, and days. - **list_all_tipalti_payment_terms** — List Tipalti payment terms, optionally filtered by id, name, externalId, days, or isDefault; all terms are returned when no filter is applied. Returns: id, externalId, name, days, isDefault. - **get_single_tipalti_payment_term_by_id** — Get a Tipalti payment term by id. Returns: id, externalId, name, days, isDefault. Required: id. - **update_a_tipalti_payment_term_by_id** — Partially update an existing Tipalti payment term by id with your requested changes. Returns the updated term including id, externalId, name, days, and isDefault. Required: id. - **list_all_tipalti_payments** — List Tipalti payments matching pre-defined search and filter criteria (id, payeeId, batchId, status, refCode, amountSubmitted, scheduledDate, submissionDate, valueDate); if no filter is specified, all payments are returned. Returns: id, batchId, payeeId, payerEntityId, refCode, providerTransactionRefCode, eWalletMessage, bankingMessage, emailSubject, submissionDate, scheduledDate, valueDate,… - **get_single_tipalti_payment_by_id** — Get a single Tipalti payment by its id. Returns the full payment object including id, status, detailedStatus, payeePaidAmount, amountSubmitted, fees, exchangeRates, tax, and customFieldValues. Required: id. - **create_a_tipalti_tax_code** — Create a new tax code in Tipalti. Returns the created tax code including its id, externalId, name, rate, isActive, and payerEntityIds. Requires name, rate, isActive, and externalId. - **list_all_tipalti_tax_codes** — List Tipalti tax codes. Returns each tax code's id, externalId, name, rate, isActive, and payerEntityIds. - **get_single_tipalti_tax_code_by_id** — Get a Tipalti tax code by id. Returns the tax code's id, externalId, name, rate, isActive, and payerEntityIds. Required: id. - **update_a_tipalti_tax_code_by_id** — Update an existing Tipalti tax code by id. Returns the updated tax code including its id, externalId, name, rate, isActive, and payerEntityIds. Required: id. - **create_a_tipalti_custom_field_value_option** — Create a new value option for a custom field in Tipalti. Returns the created value option object including id, externalId, isActive, payerEntityIds, and value. Required: custom_field_id, externalId, and value. - **get_single_tipalti_custom_field_value_option_by_id** — Get a single custom field value option by id in Tipalti. Returns: id, externalId, isActive, payerEntityIds, value. Required: custom_field_id and id. - **list_all_tipalti_custom_field_value_options** — List custom field value options for a specific custom field in Tipalti, optionally narrowed with a filter on id, externalId, isActive, valueOption, or payerEntityIds. Returns: id, externalId, isActive, payerEntityIds, value. Required: custom_field_id. - **update_a_tipalti_custom_field_value_option_by_id** — Update an existing value option for a custom field in Tipalti. Returns the updated value option object including id, externalId, isActive, payerEntityIds, and value. Required: custom_field_id and id. - **get_single_tipalti_invoice_line_by_id** — Get a specific invoice line in Tipalti by its id. Returns: id, description, quantity, unitPrice, netAmount, taxAmount, totalAmount, taxCodeId, expenseAccountId, customFieldValues. Required: invoice_id and id. - **list_all_tipalti_invoice_lines** — List invoice lines for a Tipalti invoice by its invoice_id. Returns: id, description, quantity, unitPrice, netAmount, taxAmount, totalAmount, taxCodeId, expenseAccountId, customFieldValues. Required: invoice_id. - **list_all_tipalti_payment_batch_instructions** — List all individual payment instructions in a Tipalti payment batch by its tracking batch id. Returns: id, refCode, payeeId, amountSubmitted, scheduledDate, instructionStatus, alerts. Required: payment_batch_id. - **create_a_tipalti_payee_invitation** — Create a Supplier Hub invitation for a payee in Tipalti using the payee's id. Returns: payeeId, sentTime, status. Required: payee_id. - **get_single_tipalti_payee_invitation_by_id** — Get a payee's Supplier Hub invitation in Tipalti by payee id. Returns: payeeId, sentTime, status. Required: id. ## How it works 1. **Link your customer's Tipalti account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Tipalti.** The Proxy API is a 1-to-1 mapping of the Tipalti API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Offload payee onboarding and tax compliance** — Let your users push basic payee details into Tipalti and send branded invitations to the Supplier Hub, so your platform never has to store banking info, W-9s, or W-8BENs. Ideal for creator, gig, and marketplace SaaS that want to avoid PII and tax liability. - **Automate invoice submission from procurement workflows** — When a purchase or bill is approved inside your SaaS, submit it directly to Tipalti as an invoice batch with proper GL account, tax code, and custom field coding. This removes manual double entry and keeps downstream ERP sync clean. - **Trigger mass global payouts from performance milestones** — Affiliate, ad-tech, and influencer platforms can group hundreds of earnings into a single payment batch when users hit payout thresholds, then surface real-time status back to the user. Payouts reach 190+ countries without you building treasury infrastructure. - **Show payment status and reimbursement details in-app** — Pull payment-level data like paid amount, value date, exchange rates, and banking messages to display accurate payout timelines inside your product. Users stop emailing finance to ask 'where is my payment?' - **Support multi-entity payers for vertical SaaS** — Map each of your customer's legal entities, subsidiaries, or managed properties to a Tipalti Payer Entity so bills get paid from the correct account. Essential for property management, franchise, and holding-company use cases. ## What you can build - **Embedded payee onboarding with Supplier Hub invites** — Create payees from your signup flow and dispatch Tipalti payee invitations so vendors complete banking and tax setup through Tipalti's hosted experience. - **One-click bill submission to AP** — Convert approved purchase orders or deliverables into Tipalti invoice batches of up to 200 invoices, with proper GL and tax coding carried over automatically. - **ERP-aligned expense coding UI** — Fetch GL accounts, tax codes, and custom fields from Tipalti so users code expenses inside your UI using the exact same chart of accounts their finance team expects downstream. - **Mass payout orchestration dashboard** — Create payment batches programmatically and poll payment batch instructions to show per-recipient status, failures, and expected settlement dates to end users. - **Payment status timeline for recipients** — Surface payment metadata including provider transaction references, fees, exchange rates, and banking messages so creators, contractors, or employees see exactly what happened to their money. - **Bulk payee maintenance tools** — Use bulk payee updates to synchronize status changes, payment method updates, or custom field values across thousands of vendors in a single operation. ## FAQs ### How does authentication work for Tipalti via Truto? Your end users connect their Tipalti account through Truto's connection flow. Truto manages credential storage, token refresh, and environment handling (sandbox vs. production) so you don't need to build or maintain any Tipalti-specific auth logic. ### Which Tipalti resources are available through this integration? Truto exposes tools for Payees (including bulk update and invitations), Payer Entities, Invoice Batches, Invoices and Invoice Lines, Payment Batches and Batch Instructions, Payments, Payment Terms, GL Accounts, Tax Codes, and Custom Fields with their value options. ### How do I handle Tipalti's asynchronous invoice processing? Tipalti processes invoice batches asynchronously. After calling create_a_tipalti_invoice_batch, poll get_single_tipalti_invoice_batch_by_id to inspect failedItemsCount and batchErrors, then reconcile against list_all_tipalti_invoices to confirm which invoices landed successfully. ### Can I support customers with multiple legal entities or subsidiaries? Yes. Use list_all_tipalti_payer_entities and get_single_tipalti_payer_entity_by_id to resolve which entity should be the payer for a given invoice or payment, which is critical for mid-market and enterprise customers with complex corporate structures. ### How do I keep ERP coding (GL, tax, custom fields) accurate? Pull list_all_tipalti_gl_accounts, list_all_tipalti_tax_codes, and list_all_tipalti_custom_fields (plus their value options) and expose them in your UI as dropdowns. Submitting invoices with valid IDs ensures the downstream ERP sync Tipalti performs doesn't fail. ### Do I need to store payee banking details or tax forms? No. By creating payees with create_a_tipalti_payee and sending a create_a_tipalti_payee_invitation, you redirect users to Tipalti's Supplier Hub where they enter sensitive banking and tax data directly, keeping that PII and compliance burden off your platform.