I have had several questions about how to create custom fields via the API and what values to pass. To help reduce the confusion until something better is built this should help explain how to create a custom field. This document is assuming you are using oAuth.
To start we will need this doc: xml-rpc - Keap Developer Portal
The parameters are:
- privateKey
- customFieldType
- displayName
- dataType
- headerID
privateKey: For the private key use the access_token that was received when authenticating.
customFieldType: This tells Infusionsoft what area of the application this custom field is for. Please choose from the list below. The string in parenthesis are used to help explain what the fields are on the front end of Infusionsoft.
Affiliate (Referral Partner)
Company (Company)
Contact (Contact)
ContactAction (Task/Appt/Note)
Job (Order)
JobRecurring (Subscription)
Opportunity (Opportunity)
displayName: This is the label name that will be used to show the user what field this is. Make this field recognizable by Infusionsoft users.
Note: the database name will be different if any special characters are used. The Database Name will use the alphanumeric characters in this string and strip out spaces and all other characters that are not alphanumeric. This is important to keep in mind when populating the information of a record through the API as the Database Name is used to make these calls.
dataType: This is the type of custom field that is being created. Think of the information that will be stored and how the information should be recorded when declaring this as it CAN’T be changed after creation. The Has Options row means that the options will need to be configured after creation using the update method. Please keep in mind that that dataType Name is case sensitive.
Note: After you choose the dataType it can’t be changed. Make sure this is the correct type for the information being stored and that it is the correct way that information should be displayed. (Example if you are storing an email make sure that the email custom field is used. If you want only one item selected use a radio option. If you want multiple options selected use List box. etc)
headerID: This is the hard part. If the headerID and the customFieldType don’t match then the process will return an error similar to the following where headerID is a number and customFieldType is the string that was passed:
[InvalidParameter]The group id "headerID" is an invalid header for customFieldType
To get the headerID we have two seperate ways I will call these ways A and B and you can choose the method that you would like to use and that makes sense for the integration that you are using.
Method A
This method is user dependant and should be used when the integration will be creating multiple custom field under the same area.
- Navigate to Admin > Settings
- Choose the custom field area that you are wanting and click go
- Hover over Edit next to the Header. (Note if none exists, change the dropdown that say Field to read Header)
- Hover over the Edit link next to the header and notice a number in parenthesis.
Here is what it would look like. In this instance, it is #5
[Need Image]
Method B
Since most API integrations are not going to be having user interaction to setup past the authorization here is how a custom field would be created using the API. Please note that a header must be made previously as the API doesn’t have the functionality of creating tabs or headers.
-
Query the DataFormTab table to only return results for the FormId that you are attempting to create a custom field for. The returned results should include the Ids (Example if you are wanting to use a custom contact field then the the query would only find FormIds that are -1). Below are the different FormIds:
-1 = Contact
-3 = Referral Partner
-4 = Opportunity
-5 = Task/Appt/Note
-6 = Company
-9 = Order
-10 = Subscription
Here is the link to the query information: xml-rpc - Keap Developer Portal
-
Using the Id(s) from step 1 query the DataFormGroup tab where the TabId is equal to the Id from the previous queries. You will be wanting the Id from this query.
-
The Ids from the previous queries are what are used in the custom field creation.