Function: CreateOrUpdateCustomFieldValue

The CreateOrUpdateCustomFieldValue function creates or updates a single custom field value. It applies only to bill custom fields of type ListOfValues.

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

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<customFieldValueUpdateModel>

<CustomFieldName>string</CustomFieldName>

<Code>string</Code>

<Value>string</Value>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</customFieldValueUpdateModel>

</CreateOrUpdateCustomFieldValue>

</soap:Body>

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

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

<CreateOrUpdateCustomFieldValueResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<Result>string</Result>

<Message>string</Message>

<CustomFieldValue>

<CustomFieldName>string</CustomFieldName>

<Code>string</Code>

<Value>string</Value>

<PayerEntityName>string</PayerEntityName>

<IsActive>boolean</IsActive>

</CustomFieldValue>

</CreateOrUpdateCustomFieldValueResult>

</CreateOrUpdateCustomFieldValueResponse>

</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
customFieldValueUpdateModel List of custom field details   Mandatory TipaltiCustomFieldValue

TipaltiCustomFieldValue

element

Description

Limitation

Mandatory?

Data Type
CustomFieldName
  • 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
Code The unique ID of the list item
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
Optional string
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
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 (TRUE) or Inactive (FALSE)
  • 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
CreateOrUpdateCustomFieldValueResult Contains the response parameters TipaltiCustomFieldValueUpdateResponse (extension of type TipaltiResponse)

TipaltiCustomFieldValueUpdateResponse

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
Result The result of your request to create/ update a custom field value

Valid values:

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

element

Description

Limitation

Data Type
CustomFieldName The name of the custom field
  • Max. length = 30
  • Valid characters: letters and numbers (no spaces allowed)
 string
Code The unique ID of the list item
  • Max. length = 100
  • Valid values:
    • Letters
    • Numbers
    • Spaces
string
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
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 (TRUE) or Inactive (FALSE)

Valid values:

  • TRUE
  • FALSE
 boolean