> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a subscriber
> If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.
NOTE: We support creating/updating a maximum of 140 custom fields at a time.
## OpenAPI
````yaml /api-reference/v4.json put /v4/subscribers/{id}
openapi: 3.0.3
info:
title: Kit API
version: '4.0'
servers:
- url: https://api.kit.com
security: []
paths:
/v4/subscribers/{id}:
put:
tags:
- Subscribers
summary: Update a subscriber
description: >-
If you include a custom field key that does not exist on your account,
the request returns an error. Use [List custom
fields](/api-reference/custom-fields/list-custom-fields) to retrieve
existing keys, or [Create a custom
field](/api-reference/custom-fields/create-a-custom-field) to add new
fields before setting them for
subscribers.
NOTE: We support
creating/updating a maximum of 140 custom fields at a time.
parameters:
- name: id
in: path
required: true
schema:
type: integer
example: 378
requestBody:
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
nullable: true
email_address:
type: string
fields:
type: object
additionalProperties:
type: string
description: >-
Custom field values keyed by the custom field's `key` (e.g.
`last_name`, not `Last Name`). Passing an unknown key
returns a 422 error.
required:
- email_address
example:
first_name: Alice
email_address: alice@convertkit.dev
fields:
last_name: Lamarr
birthday: Feb 17
source: landing page
role: Software developer
company: Convertkit
postal_code: '83702'
website: convertkit.com
social_media: https://www.linkedin.com/company/convertkit
how_did_you_hear_about_us: Social media
interests: Monetization
coupon: ''
responses:
'200':
description: Updates the subscriber's email address and first name
content:
application/json:
schema:
type: object
properties:
subscriber:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
additionalProperties:
type: string
description: >-
Custom field values for the subscriber, keyed by the
custom field's `key`.
required:
- id
- first_name
- email_address
- state
- created_at
- fields
required:
- subscriber
example:
subscriber:
id: 369
first_name: Alice
email_address: alice@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
fields:
birthday: Feb 17
last_name: Lamarr
source: landing page
'202':
description: >-
Returns a 202 and asynchronously updates custom fields for the
subscriber when more than 10 custom fields are included in the
request
content:
application/json:
schema:
type: object
properties:
subscriber:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
properties:
birthday:
nullable: true
company:
nullable: true
coupon:
nullable: true
how_did_you_hear_about_us:
nullable: true
interests:
nullable: true
last_name:
nullable: true
postal_code:
nullable: true
role:
nullable: true
social_media:
nullable: true
source:
nullable: true
website:
nullable: true
required:
- birthday
- company
- coupon
- how_did_you_hear_about_us
- interests
- last_name
- postal_code
- role
- social_media
- source
- website
required:
- id
- first_name
- email_address
- state
- created_at
- fields
required:
- subscriber
example:
subscriber:
id: 371
first_name: Alice
email_address: alice@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
fields:
birthday: null
company: null
coupon: null
how_did_you_hear_about_us: null
interests: null
last_name: null
postal_code: null
role: null
social_media: null
source: null
website: null
'401':
description: Returns a 401 if the token and/or account cannot be authenticated
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- The access token is invalid
'404':
description: Returns a 404 when the provided id does not exist
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- Not Found
'422':
description: Returns 422 with an error when email address is already in use
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- Email address has already been taken
security:
- API Key: []
- OAuth2: []
components:
securitySchemes:
API Key:
description: Authenticate API requests via an API Key
type: apiKey
in: header
name: X-Kit-Api-Key
OAuth2:
description: Authenticate API requests via an OAuth token
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://api.kit.com/v4/oauth/authorize
tokenUrl: https://api.kit.com/v4/oauth/token
refreshUrl: https://api.kit.com/v4/oauth/token
scopes:
read: Read access to Kit API v4
write: Write access to Kit API v4
````