Skip to main content
A custom field allows you to collect subscriber information beyond the standard fields of first name and email address. An example would be a custom field called last name so you can get the full names of your subscribers. You create a custom field, and then you’re able to use that in your forms or with the API (see the Subscribers endpoint for adding custom field values to a subscriber.) Note that you must create a custom field before you can use it with the subscribe methods on the forms, sequences, and tags endpoints.

​
List fields

Returns a list of all of your account’s custom fields.

​
Endpoint

GET /v3/custom_fields

​
Parameters

​
api_key
string
required
Your account API key
curl -X GET 'https://api.convertkit.com/v3/custom_fields?api_key=<your_public_api_key>'

{
  "custom_fields":
  [
    {
      "id": 1,
      "name": "ck_field_1_last_name",
      "key": "last_name",
      "label": "Last Name"
    },
    {
      "id": 2,
      "name": "ck_field_2_occupation",
      "key": "occupation",
      "label": "Occupation"
    }
  ]
}

​
Create field

Create a custom field for your account. The label field must be unique to your account. Whitespace will be removed from the beginning and the end of your label. Additionally, a key field and a name field will be generated for you. The key is an ASCII-only, lowercased, underscored representation of your label. This key must be unique to your account. Keys are used in personalization tags in sequences and broadcasts. Names are unique identifiers for use in the HTML of custom forms. They are made up of a combination of ID and the key of the custom field prefixed with “ck_field”. A maximum of 140 custom fields are allowed. Requests that exceed this limit will return a response of 400.

​
Endpoint

POST /v3/custom_fields

​
Parameters

​
api_secret
string
required
Your API secret key
​
label
string
required
The label(s) of the custom field. Can be a single string or an array of strings for multiple fields.
curl -X POST https://api.convertkit.com/v3/custom_fields\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "label": "Occupation" }'

curl -X POST https://api.convertkit.com/v3/custom_fields\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "label": ["Occupation", "Location"] }'

{
  "id": 1,
  "name": "ck_field_1_occupation",
  "key": "occupation",
  "label": "Occupation"
}

[{
  "id": 1,
  "name": "ck_field_1_occupation",
  "key": "occupation",
  "label": "Occupation"
},
{
  "id": 2,
  "name": "ck_field_2_location",
  "key": "location",
  "label": "Location"
}]

​
Update field

Updates a custom field label (see Create field above for more information on labels). Note that the key will change but the name remains the same when the label is updated.
An update to a custom field will break all of the liquid personalization tags in emails that reference it - e.g. if you update a Zip_Code custom field to Post_Code, all liquid tags referencing {{ subscriber.Zip_Code }} would no longer work and need to be replaced with {{ subscriber.Post_Code }}.
The API response returned when updating custom fields is dependent on the number of custom fields in the request, as shown by the examples below. A maximum of 140 custom fields are allowed. Requests that exceed this limit will return a response of 400.

​
Endpoint

PUT /v3/custom_fields/#{custom_field_id}

​
Parameters

​
api_secret
string
required
Your API secret key
​
id
integer
required
The ID of the custom field you want to update
​
label
string
required
The new label for the custom field
curl -X PUT https://api.convertkit.com/v3/custom_fields/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "label": "Profession" }'

No content will be returned.

​
Destroy field

Permanently delete a custom field. Note that this will remove all data in this field from your subscribers.

​
Endpoint

DELETE /v3/custom_fields/#{custom_field_id}

​
Parameters

​
api_secret
string
required
Your API secret key
​
id
string
required
The ID of the custom field you want to delete
curl -X DELETE https://api.convertkit.com/v3/custom_fields/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>" }'

No content will be returned.