[Agent Tools](https://tools.openkrill.app/) / [Blog](https://tools.openkrill.app/blog)

# 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 `fields` | Status | What Kit saved |
| --- | --- | --- |
| `"Signup page"` and `"Tools used"` (the labels) | 201 | Nothing: both fields null, plus 2 warnings "Unknown custom field key" |
| `"signup_page"` (the key) | 201 | The page address |
| `"tools_used"` with PUT on the subscriber id | 200 | "Link Preview", page address kept |
| `"tools_used"` with a second POST for the same email | 200 | "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.

### "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.

### "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](https://tools.openkrill.app/go/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](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

- [Kit API v4 documentation](https://developers.kit.com/): the custom field, subscriber and segment calls we made.
- [Kit plans](https://kit.com/pricing): Free up to 10,000 subscribers, sequences on Creator and higher.
- [Our Kit tag test](https://tools.openkrill.app/blog/kit-api-add-subscribers-with-a-tag): tagging sign-ups through the same API.
- [Our first Kit test](https://tools.openkrill.app/blog/kit-trial-api-broadcast-test): a scheduled broadcast through the same API.
