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

curl -X GET 'https://api.convertkit.com/v3/custom_fields?api_key=<your_public_api_key>'

​

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

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

​

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.

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

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" }'

​

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

curl -X DELETE https://api.convertkit.com/v3/custom_fields/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>" }'