Function: CreateOrUpdateCustomFields

The CreateOrUpdateCustomFields function creates, updates or deletes custom fields of all custom field types.

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

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<customFieldInfo>

<TipaltiCustomField>

<Title>string</Title>

<Description>string</Description>

<Action>string</Action>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<SubEntity>string</SubEntity>

<Type>string</Type>

<IframeDisplay>boolean</IframeDisplay>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

</TipaltiCustomField>

<TipaltiCustomField>

<Title>string</Title>

<Description>string</Description>

<Action>string</Action>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<SubEntity>string</SubEntity>

<Type>string</Type>

<IframeDisplay>boolean</IframeDisplay>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

</TipaltiCustomField>

</customFieldInfo>

</CreateOrUpdateCustomFields>

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

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

<CreateOrUpdateCustomFieldsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<CustomFieldUpdateResult>

<TipaltiCustomFieldUpdateResponse>

<Result>string</Result>

<Message>string</Message>

<CustomField>

<TipaltiCustomField>

<Title>string</Title>

<Description>string</Description>

<Action>string</Action>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<SubEntity>string</SubEntity>

<Type>string</Type>

<IframeDisplay>boolean</IframeDisplay>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

</TipaltiCustomField>

</CustomField>

</TipaltiCustomFieldUpdateResponse>

<TipaltiCustomFieldUpdateResponse>

<Result>string</Result>

<Message>string</Message>

<CustomField>

<TipaltiCustomField>

<Title>string</Title>

<Description>string</Description>

<Action>string</Action>

<Entity>

<CustomFieldEntity>string</CustomFieldEntity>

<CustomFieldEntity>string</CustomFieldEntity>

</Entity>

<SubEntity>string</SubEntity>

<Type>string</Type>

<IframeDisplay>boolean</IframeDisplay>

<Values>

<CustomFieldValue>

<Value>string</Value>

<Code>string</Code>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</Values>

</TipaltiCustomField>

</CustomField>

</TipaltiCustomFieldUpdateResponse>

</CustomFieldUpdateResult>

</CreateOrUpdateCustomFieldsResult>

</CreateOrUpdateCustomFieldsResponse>

</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
customFieldInfo
  • List of custom fields
  • Each custom field is of type TipaltiCustomField.
   Mandatory Array of TipaltiCustomField

TipaltiCustomField

element

Description

Limitation

Mandatory?

Data Type
Title
  • The name of the custom field
  • This name is used in all technical integrations (i.e., CSV uploads, APIs, IPNs, FTP update reports).
  • Max. length = 30
  • Valid characters: letters and numbers (no spaces allowed)
 Mandatory string
Description
  • Description of the custom field
  • Will display in the Tipalti Hub
 Max. length = 50 Optional string
Action
  • The action to perform
  • "CreateOrUpdate"
    • If the custom field does not exist, it is created.
    • Active bills that include the custom field will not be updated.
  • If the value is "Delete" and the custom field does not exist, an error is returned.

Valid values:

  • CreateOrUpdate (default)
  • Delete
Mandatory string
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.

 Mandatory Array of CustomFieldEntity
SubEntity Type of invoice entity Valid values:
  • Header
  • Line
 Optional string
Type
  • The type of custom field
  • Click here for descriptions of custom field types and to know which entity/ sub-entity supports each type.

Valid values:

  • FreeText (default)
  • UniqueText
  • ListOfValues
  • MultipleValues

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

 Mandatory string
IframeDisplay Indicates if the custom field is to display on the invoice PDF-generated template
  • Default = FALSE
  • Valid for all entities, sub-entities, and sub-entity combinations, except:
    • PurchaseOrder sub-entity only
    • PurchaseOrderLine sub-entity only
    • Payee entity, "ListOfValues" type
 Optional boolean
Values List of values available for the custom field  

Mandatory, if type = MultipleValues or type = ListOfValues

 Array of Custom
FieldValue
CustomFieldEntity

Element

Description

Limitation

Mandatory?

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.

 Mandatory string
CustomFieldValue

Element

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
Optional string
Code The unique ID of the list item
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
Optional string
PayerEntityName The name of the payer entity linked to the custom field
  • Max. length = 100
  • Alphanumeric characters only
 Optional string
IsActive
  • Indicates the status of the custom field: Active or Inactive
  • If you exclude this field in the request, 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.

Valid values:

  • TRUE
  • FALSE
 Optional boolean

Response parameters

Element

Description

Data Type
CreateOrUpdateCustomFieldsResult Contains the response parameters TipaltiCustomFieldsUpdateResponse (extension of type TipaltiResponse)

TipaltiCustomFieldsUpdateResponse

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
CustomFieldUpdateResult
  • Array of custom fields
  • Each custom field is of type TipaltiCustomFieldUpdateResponse.
   Array of TipaltiCustomField
UpdateResponse
TipaltiCustomFieldUpdateResponse

element

description

Limitation

data type
Result The result of your request to create, update or delete a custom field

Valid values:

  • Other
  • Success
  • FieldDoesntExist
  • DuplicateField
  • EmptyTitle
  • TooLongTitle
  • IllegalCharsTitle
  • RestrictedTitle
  • EmptyMultiValueSelectionField
  • MultiValuesAreNotUnique
  • ValueTypeNotSupported
  • UnknownPayerEntity
 string
Message A description of the result   string
CustomField Returns custom field details   TipaltiCustomField
TipaltiCustomField

element

Description

Limitation

Data Type
Title
  • The name of the custom field
  • This name is used in all technical integrations (i.e., CSV uploads, APIs, IPNs, FTP update reports).
  • Max. length = 30
  • Valid characters: letters and numbers (no spaces allowed)
 string
Description
  • Description of the custom field
  • Will display in the Tipalti Hub
 Max. length = 50 string
Action
  • The action to perform
  • "CreateOrUpdate"
    • If the custom field does not exist, it is created.
    • Active bills that include the custom field will not be updated.
  • If the value is "Delete" and the custom field does not exist, an error is returned.

Valid values:

  • CreateOrUpdate (default)
  • Delete
string
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
SubEntity Type of invoice entity Valid values:
  • Header
  • Line
 string
Type
  • The type of custom field
  • Click here for descriptions of custom field types and to know which entity/sub-entity supports each type.

Valid values:

  • FreeText (default)
  • UniqueText
  • ListOfValues
  • MultipleValues
string
IframeDisplay Indicates if the custom field is to display on the invoice PDF-generated template
  • Default = FALSE
  • Valid for all entities, sub-entities, and sub-entity combinations, except:
    • PurchaseOrder sub-entity only
    • PurchaseOrderLine sub-entity only
    • Payee entity, "ListOfValues" type
 boolean
Values List of values available for the custom field   Array of Custom
FieldValue
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
PayerEntityName The name of the payer entity linked to the custom field
  • Max. length = 100
  • Alphanumeric characters only
 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