> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.beehiiv.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server. # Create publication field OAuth Scope: publication_fields:write POST https://api.beehiiv.com/v2/workspaces/publication_fields Content-Type: application/json This feature is currently in beta and the API is subject to change. Define a new publication field for the workspace. The field is created active, and every publication in the workspace can immediately set a value for it. A `json` field must set `value_source` to `fetched`, an `endpoint_url`, and the `response_keys` it declares. Every other kind must be `static` and carry no `endpoint_url`. All kinds except `json` and `rss_feed_url` require a `default_value`. Requires an API key with access to every publication in the workspace. Reference: https://developers.beehiiv.com/api-reference/publication-fields/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an object. - `display` (string, required) — The human readable label for the field. - `kind` (enum, required) — The type of value the field holds. - Allowed values: `text`, `number`, `boolean`, `date`, `color`, `url`, `image_url`, `rss_feed_url`, `json` - `name` (string, optional) — The merge tag key for the field, unique within the workspace. Derived from `display` when omitted. Normalized to start with a letter and contain only lowercase letters, numbers and underscores, so `Support Email` is stored as `support_email`. A `date` or `number` field also claims its format variants, so `launch_date_mdy` is rejected with `NAME_CLASHES` while a `date` field named `launch_date` exists, and the other way around. - `value_source` (enum, optional) — Where the value for each publication comes from. Defaults to `static`. - Allowed values: `static`, `fetched` - `default_value` (string, optional) — The value used for publications that have not set one of their own. Required for every kind except `json` and `rss_feed_url`. - `endpoint_url` (string, optional) — The URL the value is retrieved from. Required when `value_source` is `fetched` and rejected otherwise. May contain merge tags that resolve per publication. - `response_keys` (list of PublicationFieldResponseKey, optional) — The keys declared within the fetched JSON response body. Required when `kind` is `json` and rejected otherwise. A `number` or `date` key also claims its format variants, so a key `temp_round2` is rejected with `RESPONSE_KEYS_CLASHES` beside a `number` key named `temp`. ## Response ### 201 Created - `data` (PublicationField, required) ## Errors ### 400 Bad Request Error Bad Request - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 401 Unauthorized Error Unauthorized. The API key or OAuth access token is missing, invalid, or expired. - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 403 Forbidden Error Forbidden - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 404 Not Found Error Resource Not Found - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 429 Too Many Requests Error Rate Limit Exceeded - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 500 Internal Server Error Internal Server Error - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ## Types ### PublicationFieldResponseKey - `key` (string, required) — The name of the key within the JSON response body. - `kind` (enum, required) — The type of value the key holds. - Allowed values: `text`, `number`, `date`, `url`, `image_url` ### PublicationField - `id` (string, required) — The prefixed ID of the publication field. - `name` (string, required) — The merge tag key for the field. This is what content references, and it is unique within the workspace. - `display` (string, required) — The human readable label for the field. - `kind` (enum, required) — The type of value the field holds. - Allowed values: `text`, `number`, `boolean`, `date`, `color`, `url`, `image_url`, `rss_feed_url`, `json` - `value_source` (enum, required) — Where the value for each publication comes from. - Allowed values: `static`, `fetched` - `response_keys` (list of PublicationFieldResponseKey, required) — The keys declared within the fetched JSON response body. Empty unless `kind` is `json`. - `status` (enum, required) — Whether the field is currently active or has been archived. - Allowed values: `active`, `archived` - `created` (integer, required) — The time the field was created. Measured in seconds since the Unix epoch. - `updated` (integer, required) — The time the field was last updated. Measured in seconds since the Unix epoch. - `default_value` (string, optional) — The value used for publications that have not set one of their own. Null when the field has none configured; `json` and `rss_feed_url` fields are the only kinds not required to have one. - `endpoint_url` (string, optional) — The URL the value is retrieved from. Present only when `value_source` is `fetched`, and may contain merge tags that resolve per publication. ### ErrorDetail - `message` (string, required) - `code` (string, required) ## Examples **Request** ```json { "display": "Support email", "kind": "text", "default_value": "support@beehiiv.com" } ``` **Response** ```json { "data": { "id": "pub_field_00000000-0000-0000-0000-000000000000", "name": "support_email", "display": "Support email", "kind": "text", "value_source": "static", "response_keys": [], "status": "active", "created": 1700000000, "updated": 1700000000, "default_value": "support@beehiiv.com", "endpoint_url": null } } ``` **SDK Code** ```python import requests url = "https://api.beehiiv.com/v2/workspaces/publication_fields" payload = { "display": "Support email", "kind": "text", "default_value": "support@beehiiv.com" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.beehiiv.com/v2/workspaces/publication_fields'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"display":"Support email","kind":"text","default_value":"support@beehiiv.com"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.beehiiv.com/v2/workspaces/publication_fields" payload := strings.NewReader("{\n \"display\": \"Support email\",\n \"kind\": \"text\",\n \"default_value\": \"support@beehiiv.com\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.beehiiv.com/v2/workspaces/publication_fields") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"display\": \"Support email\",\n \"kind\": \"text\",\n \"default_value\": \"support@beehiiv.com\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.beehiiv.com/v2/workspaces/publication_fields") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"display\": \"Support email\",\n \"kind\": \"text\",\n \"default_value\": \"support@beehiiv.com\"\n}") .asString(); ``` ```php request('POST', 'https://api.beehiiv.com/v2/workspaces/publication_fields', [ 'body' => '{ "display": "Support email", "kind": "text", "default_value": "support@beehiiv.com" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.beehiiv.com/v2/workspaces/publication_fields"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"display\": \"Support email\",\n \"kind\": \"text\",\n \"default_value\": \"support@beehiiv.com\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "display": "Support email", "kind": "text", "default_value": "support@beehiiv.com" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/workspaces/publication_fields")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > Build your audience with beehiiv's API and SDKs. Create new subscribers and posts, get real-time notifications of subscription activity, and more.