Function: GetCustomFields

The GetCustomFields function returns the payer's defined custom fields.

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

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

</GetCustomFields>

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

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

<GetCustomFieldsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<CustomFields>

<CustomFieldInfo>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<Title>string</Title>

<Description>string</Description>

<ValueType>string</ValueType>

<SubEntity>string</SubEntity>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<LimitedToPayerEntities>

<string>string</string>

<string>string</string>

</LimitedToPayerEntities>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

<Category>string</Category>

</CustomFieldInfo>

<CustomFieldInfo>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<Title>string</Title>

<Description>string</Description>

<ValueType>string</ValueType>

<SubEntity>string</SubEntity>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<LimitedToPayerEntities>

<string>string</string>

<string>string</string>

</LimitedToPayerEntities>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

<Category>string</Category>

</CustomFieldInfo>

</CustomFields>

</GetCustomFieldsResult>

</GetCustomFieldsResponse>

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

Response parameters

element

description

data type
GetCustomFieldsResult Contains the response parameters TipaltiGetCustomFieldsResponse

TipaltiGetCustomFieldsResponse

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
CustomFields
  • List of custom fields
  • Each custom field is of type CustomFieldInfo.
   Array of CustomFieldInfo
CustomFieldInfo

element

Description

Limitation

Data Type
Entity
  • Type of custom field entity
  • The following combinations are allowed:
    • Bill + PurchaseOrder
    • Bill Line + PurchaseOrder Line

Valid values:

  • PaymentOrder
  • Payee
  • Invoice
  • PurchaseOrder
  • Invoice + PurchaseOrder

Note: The entity type of the custom field cannot be changed.

 Array of CustomFieldEntity
Title The name of the custom field
  • Max. length = 30
  • Valid characters:
    • Letters
    • Numbers
    • Spaces
 string
Description Description of the custom field Max. length = 50 string
ValueType
  • The type of custom field
  • Click here for a description of each type.

Valid values:

  • FreeText (default)
  • UniqueText
  • ListOfValues
  • MultipleValues
string
SubEntity Type of invoice entity

Valid values:

  • Header
  • Line
 string
Values List of values available for the custom field

Mandatory, if type = MultipleValues or type = ListOfValues

 Array of CustomFieldValue
Category
  • The category of custom field:
    • Coding - Bill approvers are able to edit bill and bill line custom fields of this category. This value only displays for the following bill flows:
      • Invoice processing
      • Self-billing with internal approval only
    • Taxation - A custom field related to taxation
    • Other - A category other than "Coding" or "Taxation"
  • This field is only returned if:
    • The payer has enabled, with Tipalti, approvers to edit custom fields.
    • The entity is "Invoice" or InvoiceLine".

Valid values:

  • Coding
  • Taxation
  • Other
 string
CustomFieldEntity

Element

Description

Limitation

Data Type
CustomFieldEntity
  • Type of custom field entity
  • The following combinations are allowed:
    • Bill + PurchaseOrder
    • Bill Line + PurchaseOrder Line

Valid values:

  • PaymentOrder
  • Payee
  • Invoice
  • PurchaseOrder
  • Invoice + PurchaseOrder

Note: The entity type of the custom field cannot be changed.

 string
CustomFieldValue

Element

Description

Limitation

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
string
Code The unique ID of the list item
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
string
LimitedToPayerEntities element A list of names of the Payer Entities linked to the Custom Field Value
  • Max. length = 100
  • Alphanumeric characters only
 Array of string
IsActive
  • Indicates the status of the custom field: active or inactive
  • 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.

Valid values:

  • TRUE
  • FALSE
 Optional
string

element

description

limitation

data type
string Array of strings each representing a Payer Entity name
  • Max. length = 100
  • Alphanumeric characters only
 string