Skip to the content
Agent Tools

Kit API custom fields: send the key, not the label, or the value is dropped with only a warning

We saved 2 custom fields on Kit subscribers through API v4. When we sent the field's label, "Signup page", Kit answered 201 Created but saved nothing. The only hint was a warnings list. When we sent the key, signup_page, the value saved. A second add with the same email address updated the fields and kept the old ones.

By OpenKrill. Published 2026-11-03. All calls are our own, made on 2026-10-28 on the OpenKrill Kit account during its 14-day Creator trial. The test subscribers were our own addresses, and no email went out.

This post has one affiliate link, to Kit. If you sign up or pay through it, Kit may pay us a commission. It's marked where it appears, and every step below works the same if you go to kit.com yourself.

The short answer

Custom fields let you keep a fact on each subscriber, such as the page they signed up on. Make the field once, read the key Kit returns, and send that key in fields. Check the warnings list in every answer, because a wrong name doesn't make the call fail.

What we sent in fieldsStatusWhat Kit saved
"Signup page" and "Tools used" (the labels)201Nothing: both fields null, plus 2 warnings "Unknown custom field key"
"signup_page" (the key)201The page address
"tools_used" with PUT on the subscriber id200"Link Preview", page address kept
"tools_used" with a second POST for the same email200"Link Preview, Site Check", page address kept

What buyers worry about, and what we found

"Will a typo in a field name break my sign-up form?"

It won't, and that's the problem. Kit still created the subscriber and returned 201, so a sign-up form keeps working. The value is just gone. In the Kit app, that subscriber's Custom Fields panel listed only the email and first name, with "Show 2 empty fields" under them.

Kit subscriber page for Guide Three: Custom Fields shows only email address and first name, with Show 2 empty fields.

"Where do I find the key?"

In the answer you get when you make the field. We sent the label "Signup page" and got back the key signup_page and an internal name, ck_field_1411370_signup_page. Kit lowercased the label and put underscores where the spaces were. GET /v4/custom_fields lists all of them later.

"Does updating one field wipe the others?"

It didn't. A PUT on the subscriber and a second POST with the same email each changed only the field we sent. The second POST came back 200 instead of 201, so you can use it to update from a form when you don't store Kit's subscriber id.

Kit subscriber page for Guide Four: Custom Fields shows Signup page /blog/fix-whatsapp-link-preview-no-image and Tools used Link Preview, Site Check.

"How fast are the calls?"

All 10 calls in this run answered in 1.06 to 1.55 seconds.

How we ran it

OpenKrill is a Kit affiliate and may receive a commission if you sign up or buy through the Kit link below. That is the only string attached, and the rest of this post works the same without it.

We used our Kit account and one API key from the developer settings, sent in the X-Kit-Api-Key header.

Skip our link if you like. The direct address, with no tracking, is https://kit.com.

  1. Make the fields. POST /v4/custom_fields with {"label": "Signup page"}, then again for "Tools used". Note each key.
  2. Add a sign-up with a field. POST /v4/subscribers with email_address, first_name and "fields": {"signup_page": "/blog/..."}.
  3. Add a field later. Use PUT /v4/subscribers/{id} or the same POST again, with only the new field in fields.
  4. Watch for warnings. If the answer has a warnings list, log it or stop. In our test, that list was the only sign a field had been dropped.
curl -X POST https://api.kit.com/v4/subscribers \
  -H "X-Kit-Api-Key: $KIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "reader@example.com", "fields": {"signup_page": "/blog/some-post"}}'

When a paid plan makes sense

Custom fields and the API work on the free plan, which allows up to 10,000 subscribers. A field like the sign-up page earns its keep when you send different emails by it. Kit's segments group people by fields and tags, and our account had none yet (GET /v4/segments returned an empty list). Sequences that branch on a field need Creator or higher, so that's the point to pay.

What this test does not show

  • 2 test subscribers and 2 text fields on one account on one day.
  • We didn't make a segment, or test how fast one picks up a new field value.
  • We didn't test bulk imports or Kit's own forms with custom fields.

Frequently asked questions

Why is my Kit custom field empty after an API call?

You probably sent the field's label instead of its key. In our test, Kit still returned 201 but saved null, with the warning "Unknown custom field key".

How do I update a Kit subscriber's custom field with the API?

Use PUT /v4/subscribers/{id}, or POST /v4/subscribers again with the same email. Both changed only the field we sent and kept the rest.

What key does Kit give a custom field?

The label lowercased, with underscores for spaces. "Signup page" became signup_page in our test.

Sources