--- title: "Create an event" method: POST path: "/api/v2/events" tags: ["Events"] --- # Create an event `POST /api/v2/events` ## Request - Base URL: `https://yournation.nationbuilder.com` - URL: `https://yournation.nationbuilder.com/api/v2/events` - Auth: HTTP bearer Create events with the provided payload. Events must be created with a page resource, which can be sideposted as shown in the example payload. Events must also have a start_at time. ## Request body - EventCreateRequest: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes. - `data` object, required - `type` 'events', required: The JSON:API resource type of the resource being created. - `attributes` object: The write-only attributes of a event. - `accept_rsvps` boolean: Allows people to RSVP for the event. If set to false, the event will display, but people will not be able to submit an RSVP to it. - `additional_rsvps_count` integer, nullable: Number of offline RSVPs to add to event's total capacity - `allow_guests` boolean, nullable: Allows RSVP to enter the number of guests they will bring to the event. - `attending_count` integer, nullable: The number of attendees for the current event. - `auto_response_broadcaster_id` string, nullable: ID of the broadcaster that the event's auto response will be sent by - `auto_response_content` string, nullable: Email content of the auto response sent people RSVP-ing to the event. - `auto_response_subject` string, nullable: Email subject of the auto response sent people RSVP-ing to the event. - `capacity_count` integer, nullable: The number of RSVPs allowed. If set to 0, there is no limit to number of RSVPs. - `contact_email` string, nullable: The email address of the contact person. - `contact_email_private` boolean, nullable: Flag used to hide the contact person's email address on public event pages. - `contact_name` string, nullable: The name of the contact person for the event. - `contact_phone_number` string, nullable: The phone number of the contact person. - `contact_phone_private` boolean, nullable: Flag used to hide the contact person's phone number on public event pages. - `content` string, nullable: Content displayed on the public event page - `donation_tracking_code_id` string, nullable: ID of the donation tracking code to be associated with ticket purchases for the event - `duration` integer, nullable: Duration of the event in seconds. Updates the end_at time of the event. - `event_form_address` 'required' | 'optional' | 'hidden' | 'null', nullable: Attribute used to set address input requirements for RSVPs - `event_form_phone` 'required' | 'optional' | 'hidden' | 'null', nullable: Attribute used to set phone number input requirements for RSVPs - `gather_volunteers` boolean, nullable: Attribute used to ask RSVPs if they want to volunteer in the public event form. - `point_person_id` string, nullable: ID of the point person assigned to RSVPs - `private` boolean, nullable: When true, the event is hidden in the website - `sends_auto_response` boolean, nullable: Automatically send person RSVPing an email - `show_guests` boolean, nullable: Controls where RSVPs are shown on the event page - `start_at` string, date-time, nullable: Start time of the event - `time_zone` 'Abu Dhabi' | 'Adelaide' | 'Alaska' | 'Almaty' | 'America/Adak' | 'America/Edmonton' | 'America/Inuvik' | 'America/Vancouver' | 'America/Winnipeg' | 'American Samoa' | 'Amsterdam' | 'Antarctica/Troll' | 'Arizona' | 'Astana' | 'Athens' | 'Atlantic Time (Canada)' | 'Auckland' | 'Australia/Eucla' | 'Australia/Lord_Howe' | 'Azores' | 'Baghdad' | 'Baku' | 'Bangkok' | 'Beijing' | 'Belgrade' | 'Berlin' | 'Bern' | 'Bogota' | 'Brasilia' | 'Bratislava' | 'Brisbane' | 'Brussels' | 'Bucharest' | 'Budapest' | 'Buenos Aires' | 'Cairo' | 'Canada/Yukon' | 'Canberra' | 'Cape Verde Is.' | 'Caracas' | 'Casablanca' | 'Central America' | 'Central Time (US & Canada)' | 'Chatham Is.' | 'Chennai' | 'Chihuahua' | 'Chongqing' | 'Copenhagen' | 'Darwin' | 'Dhaka' | 'Dublin' | 'Eastern Time (US & Canada)' | 'Edinburgh' | 'Ekaterinburg' | 'Fiji' | 'Georgetown' | 'Greenland' | 'Guadalajara' | 'Guam' | 'Hanoi' | 'Harare' | 'Hawaii' | 'Helsinki' | 'Hobart' | 'Hong Kong' | 'Indiana (East)' | 'International Date Line West' | 'Irkutsk' | 'Islamabad' | 'Istanbul' | 'Jakarta' | 'Jerusalem' | 'Kabul' | 'Kaliningrad' | 'Kamchatka' | 'Karachi' | 'Kathmandu' | 'Kolkata' | 'Krasnoyarsk' | 'Kuala Lumpur' | 'Kuwait' | 'Kyiv' | 'La Paz' | 'Lima' | 'Lisbon' | 'Ljubljana' | 'London' | 'Madrid' | 'Magadan' | 'Marshall Is.' | 'Mazatlan' | 'Melbourne' | 'Mexico City' | 'Mid-Atlantic' | 'Midway Island' | 'Minsk' | 'Monrovia' | 'Monterrey' | 'Montevideo' | 'Moscow' | 'Mountain Time (US & Canada)' | 'Mumbai' | 'Muscat' | 'Nairobi' | 'New Caledonia' | 'New Delhi' | 'Newfoundland' | 'Novosibirsk' | 'Nuku'alofa' | 'Osaka' | 'Pacific Time (US & Canada)' | 'Pacific/Gambier' | 'Pacific/Kiritimati' | 'Pacific/Marquesas' | 'Pacific/Pitcairn' | 'Paris' | 'Perth' | 'Port Moresby' | 'Prague' | 'Pretoria' | 'Puerto Rico' | 'Quito' | 'Rangoon' | 'Riga' | 'Riyadh' | 'Rome' | 'Samara' | 'Samoa' | 'Santiago' | 'Sapporo' | 'Sarajevo' | 'Saskatchewan' | 'Seoul' | 'Singapore' | 'Skopje' | 'Sofia' | 'Solomon Is.' | 'Srednekolymsk' | 'Sri Jayawardenepura' | 'St. Petersburg' | 'Stockholm' | 'Sydney' | 'Taipei' | 'Tallinn' | 'Tashkent' | 'Tbilisi' | 'Tehran' | 'Tijuana' | 'Tokelau Is.' | 'Tokyo' | 'UTC' | 'Ulaanbaatar' | 'Urumqi' | 'Vienna' | 'Vilnius' | 'Vladivostok' | 'Volgograd' | 'Warsaw' | 'Wellington' | 'West Central Africa' | 'Yakutsk' | 'Yerevan' | 'Zagreb' | 'Zurich' | 'null', nullable: Time zone the event takes place in - `user_ticket_currency` string, nullable: Currency tickets are purchased in. Used only when selling tickets outside of NationBuilder - `user_ticket_price_in_cents` integer, nullable: Price in cents of the ticket level. Used only when selling tickets outside of NationBuilder - `user_ticket_purchase_url` string, nullable: URL to third-party seller where tickets are being sold. Used only when selling tickets outside of NationBuilder - `uses_shifts` boolean, nullable: Flag controlling whether RSVPs will be asked to sign up for shifts during the event. - `uses_tickets` boolean, nullable: Flag controller whether tickets will be sold to people RSVPing to the event - `venue_name` string, nullable: Name of the venue - `venue_address_attributes` object, nullable: Attribute used to write data to the given event's Venue address. When an address already exists, provided values will be used to patch the existing address data, only overwriting values provided in the payload. When no address exists, the existing data will be used to persist a new address. - `relationships` object - `page` object - `data` object: Identifies a related resource written in the same request (a sidepost), an extension to JSON:API. For method create, the temp-id links this relationship entry to the matching object in the request's top-level included array; the other methods identify an existing related resource by id. Omitting method associates an existing resource without modifying it. - `type` 'pages', required: The JSON:API type of the related resource. - `id` string: The ID of an existing related resource; used with every method except create. - `temp-id` string: Client-generated temporary ID tying this relationship to an entry in the included array when creating the related resource. - `method` 'create' | 'update' | 'destroy' | 'disassociate': The sidepost operation to perform on the related resource. - `included` object[] - `type` 'pages' - `temp-id` string - `attributes` object: Writable page attributes for sideposting; excludes page_type_name which the parent resource sets. - `author_id` string, nullable: The author of the page. - `excerpt` string, nullable: Longer page description used for search engine optimization. - `external_id` string, nullable: Optional reference for pages imported from an external service. - `headline` string, nullable: This is a header rendered above the page content. - `name` string: The name of the page. - `parent_id` string, nullable: The parent page ID (null for top-level pages). - `permission_level` 'anyone' | 'logged_in' | 'members' | 'control_panel_users' | 'admins': The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only). - `site_id` string: The site this page belongs to. - `slug` string: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug] - `status` 'archived' | 'deleted' | 'expired' | 'hidden' | 'published' | 'rule_violated' | 'unlisted': The page status - describing the visibility of the page. - `title` string: Brief page description seen on search engines. - `page_type_name` 'Event': Must be 'Event' for this endpoint. ## Response `201` The newly created event. - EventShowResponse: The JSON:API top-level document shape for responses returning a single resource under the data member. - `data` object, required: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource. - `id` string, required: Unique identifier of the resource. - `type` 'events', required: The JSON:API resource type. - `attributes` object: The read-only attributes of a event. - `accept_rsvps` boolean: Allows people to RSVP for the event. If set to false, the event will display, but people will not be able to submit an RSVP to it. - `additional_rsvps_count` integer, nullable: Number of offline RSVPs to add to event's total capacity - `allow_guests` boolean, nullable: Allows RSVP to enter the number of guests they will bring to the event. - `attending_count` integer, nullable: The number of attendees for the current event. - `auto_response_broadcaster_id` string, nullable: ID of the broadcaster that the event's auto response will be sent by - `auto_response_content` string, nullable: Email content of the auto response sent people RSVP-ing to the event. - `auto_response_subject` string, nullable: Email subject of the auto response sent people RSVP-ing to the event. - `capacity_count` integer, nullable: The number of RSVPs allowed. If set to 0, there is no limit to number of RSVPs. - `contact_email` string, nullable: The email address of the contact person. - `contact_email_private` boolean, nullable: Flag used to hide the contact person's email address on public event pages. - `contact_name` string, nullable: The name of the contact person for the event. - `contact_phone_number` string, nullable: The phone number of the contact person. - `contact_phone_private` boolean, nullable: Flag used to hide the contact person's phone number on public event pages. - `content` string, nullable: Content displayed on the public event page - `donation_tracking_code_id` string, nullable: ID of the donation tracking code to be associated with ticket purchases for the event - `duration` integer, nullable: Duration of the event in seconds. Updates the end_at time of the event. - `event_form_address` 'required' | 'optional' | 'hidden' | 'null', nullable: Attribute used to set address input requirements for RSVPs - `event_form_phone` 'required' | 'optional' | 'hidden' | 'null', nullable: Attribute used to set phone number input requirements for RSVPs - `gather_volunteers` boolean, nullable: Attribute used to ask RSVPs if they want to volunteer in the public event form. - `point_person_id` string, nullable: ID of the point person assigned to RSVPs - `private` boolean, nullable: When true, the event is hidden in the website - `sends_auto_response` boolean, nullable: Automatically send person RSVPing an email - `show_guests` boolean, nullable: Controls where RSVPs are shown on the event page - `start_at` string, date-time, nullable: Start time of the event - `time_zone` 'Abu Dhabi' | 'Adelaide' | 'Alaska' | 'Almaty' | 'America/Adak' | 'America/Edmonton' | 'America/Inuvik' | 'America/Vancouver' | 'America/Winnipeg' | 'American Samoa' | 'Amsterdam' | 'Antarctica/Troll' | 'Arizona' | 'Astana' | 'Athens' | 'Atlantic Time (Canada)' | 'Auckland' | 'Australia/Eucla' | 'Australia/Lord_Howe' | 'Azores' | 'Baghdad' | 'Baku' | 'Bangkok' | 'Beijing' | 'Belgrade' | 'Berlin' | 'Bern' | 'Bogota' | 'Brasilia' | 'Bratislava' | 'Brisbane' | 'Brussels' | 'Bucharest' | 'Budapest' | 'Buenos Aires' | 'Cairo' | 'Canada/Yukon' | 'Canberra' | 'Cape Verde Is.' | 'Caracas' | 'Casablanca' | 'Central America' | 'Central Time (US & Canada)' | 'Chatham Is.' | 'Chennai' | 'Chihuahua' | 'Chongqing' | 'Copenhagen' | 'Darwin' | 'Dhaka' | 'Dublin' | 'Eastern Time (US & Canada)' | 'Edinburgh' | 'Ekaterinburg' | 'Fiji' | 'Georgetown' | 'Greenland' | 'Guadalajara' | 'Guam' | 'Hanoi' | 'Harare' | 'Hawaii' | 'Helsinki' | 'Hobart' | 'Hong Kong' | 'Indiana (East)' | 'International Date Line West' | 'Irkutsk' | 'Islamabad' | 'Istanbul' | 'Jakarta' | 'Jerusalem' | 'Kabul' | 'Kaliningrad' | 'Kamchatka' | 'Karachi' | 'Kathmandu' | 'Kolkata' | 'Krasnoyarsk' | 'Kuala Lumpur' | 'Kuwait' | 'Kyiv' | 'La Paz' | 'Lima' | 'Lisbon' | 'Ljubljana' | 'London' | 'Madrid' | 'Magadan' | 'Marshall Is.' | 'Mazatlan' | 'Melbourne' | 'Mexico City' | 'Mid-Atlantic' | 'Midway Island' | 'Minsk' | 'Monrovia' | 'Monterrey' | 'Montevideo' | 'Moscow' | 'Mountain Time (US & Canada)' | 'Mumbai' | 'Muscat' | 'Nairobi' | 'New Caledonia' | 'New Delhi' | 'Newfoundland' | 'Novosibirsk' | 'Nuku'alofa' | 'Osaka' | 'Pacific Time (US & Canada)' | 'Pacific/Gambier' | 'Pacific/Kiritimati' | 'Pacific/Marquesas' | 'Pacific/Pitcairn' | 'Paris' | 'Perth' | 'Port Moresby' | 'Prague' | 'Pretoria' | 'Puerto Rico' | 'Quito' | 'Rangoon' | 'Riga' | 'Riyadh' | 'Rome' | 'Samara' | 'Samoa' | 'Santiago' | 'Sapporo' | 'Sarajevo' | 'Saskatchewan' | 'Seoul' | 'Singapore' | 'Skopje' | 'Sofia' | 'Solomon Is.' | 'Srednekolymsk' | 'Sri Jayawardenepura' | 'St. Petersburg' | 'Stockholm' | 'Sydney' | 'Taipei' | 'Tallinn' | 'Tashkent' | 'Tbilisi' | 'Tehran' | 'Tijuana' | 'Tokelau Is.' | 'Tokyo' | 'UTC' | 'Ulaanbaatar' | 'Urumqi' | 'Vienna' | 'Vilnius' | 'Vladivostok' | 'Volgograd' | 'Warsaw' | 'Wellington' | 'West Central Africa' | 'Yakutsk' | 'Yerevan' | 'Zagreb' | 'Zurich' | 'null', nullable: Time zone the event takes place in - `user_ticket_currency` string, nullable: Currency tickets are purchased in. Used only when selling tickets outside of NationBuilder - `user_ticket_price_in_cents` integer, nullable: Price in cents of the ticket level. Used only when selling tickets outside of NationBuilder - `user_ticket_purchase_url` string, nullable: URL to third-party seller where tickets are being sold. Used only when selling tickets outside of NationBuilder - `uses_shifts` boolean, nullable: Flag controlling whether RSVPs will be asked to sign up for shifts during the event. - `uses_tickets` boolean, nullable: Flag controller whether tickets will be sold to people RSVPing to the event - `venue_name` string, nullable: Name of the venue - `page_id` string, nullable: ID of the page associated with the event - `included` Resource[]: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type. - `id` string, required: Unique identifier of the resource. - `type` string, required: The JSON:API resource type. - `attributes` object: The attributes of the resource, as documented for its resource type. - `relationships` object: References from this resource to other resources in the document. - `meta` object: Non-standard information about the document. Empty unless the endpoint has metadata to convey. ## Other responses - `400`: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload. - `401`: The access token is missing, expired, or not authorized to access this resource. - `422`: Model validations failed for the resource being created or updated. Unlike this API's other errors, validation failures are returned as a JSON:API errors document locating each invalid field. - `429`: The access token has exceeded its request quota for the current rate-limit window. ## Changes - **2026-11-05** `d5c88ca497ac`: 4 breaking, 2 warning, 8 info - added `#/components/schemas/create_request_document, subschema #2` to the request body `allOf` list - the request's body type changed from `object` to no type - the response's body type changed from `object` to no type for status `201` - removed the required property `data` from the response with the `201` status - …10 more - **2026-02-14** `31995b0a1e61`: 4 breaking, 9 warning, 11 info - the request property `included/items/attributes/name` became not nullable - the request property `included/items/attributes/page_type_name` became not nullable - the request property `included/items/attributes/slug` became not nullable - the request property `included/items/attributes/title` became not nullable - …20 more [Operation history](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/changes/api/v2/events/post.md) --- [API](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api.md) - [All operations](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/revisions/d5c88ca497ac?raw)