> ## Documentation Index > Fetch the complete documentation index at: https://developer.swoogo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Field > Creates a new custom field definition for events. Specify the field name, type (text, dropdown, checkbox, etc.), visibility, sort order, and choices (for selection-type fields). The field will become available for data entry on events. ## OpenAPI ````yaml /api-reference/openapi.yaml post /events/field openapi: 3.1.0 info: title: Swoogo API version: 1.0.0 summary: REST API for the Swoogo event management platform description: > The Swoogo API provides programmatic access to manage events, registrants, sessions, speakers, sponsors, and related resources on the Swoogo event management platform. ## Authentication The API uses OAuth 2.0 with the **client credentials** grant type. 1. **Get your credentials** — Log in to Swoogo and go to **My Profile > API Credentials** to find your consumer key and secret. 2. **Encode credentials** — URL-encode the key and secret (RFC 1738), concatenate them with a colon (`key:secret`), then Base64-encode the result. 3. **Request a token** — `POST /oauth2/token` with your encoded credentials in the `Authorization: Basic {encoded}` header and `grant_type=client_credentials` in the body. 4. **Use the token** — Include `Authorization: Bearer {access_token}` on all subsequent requests. > Tokens expire after **30 minutes**. Request a new token when you receive a `401` response. ## Rate Limiting API requests are rate-limited to **2,000 requests per 10-minute window** per API credential. List endpoints cost **10 credits** per call; all other endpoints cost **1 credit**. Rate limit status is returned in response headers: | Header | Description | |--------|-------------| | `X-Rate-Limit-Limit` | Maximum requests allowed in the current window | | `X-Rate-Limit-Remaining` | Requests remaining in the current window | | `X-Rate-Limit-Reset` | Seconds until the window resets | When the limit is exceeded, the API returns `429 Too Many Requests`. ## Pagination All list endpoints return paginated results in this envelope: ```json { "items": [...], "_links": { "self": { "href": "..." }, "first": { "href": "..." }, "last": { "href": "..." } }, "_meta": { "totalCount": 95, "pageCount": 5, "currentPage": 1, "perPage": 20 } } ``` Control pagination with these query parameters: | Parameter | Default | Max | Description | |-----------|---------|-----|-------------| | `page` | 1 | — | Page number (1-indexed) | | `per-page` | 20 | 1000 | Items per page. Capped at **200** when using `expand`. | Pagination metadata is also returned in `X-Pagination-*` response headers. ## Filtering and Sorting Use the `search` parameter to filter results. Combine multiple conditions with `&`. **Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `*contains*`, `*beginswith*`, `*endswith*`, `*in*` **Examples:** - `search=registration_status=confirmed` — exact match - `search=created_at>=2024-01-01` — date range - `search=last_name=*beginswith*Sm` — starts with "Sm" - `search=status=*in*confirmed|attended` — matches any value (pipe-separated) - `search=id>100®istration_status=confirmed` — multiple conditions (AND by default) Set `searchCondition=or` to match **any** condition instead of all. Use `sort` to order results. Prefix with `-` for descending: `sort=-created_at`. ## Field Selection and Expansion Use `fields` to request only the fields you need: `fields=id,email,first_name,last_name`. When omitted, a default subset of fields is returned. Use `expand` to include related objects in the response: `expand=homeAddress,sessions`. Each resource documents its available expand values. Using `expand` caps the page size at **200**. ## Errors All errors return a consistent JSON response: ```json { "name": "Not Found", "message": "The requested resource does not exist.", "code": 0, "status": 404 } ``` | Status | Meaning | |--------|---------| | `400` | Bad Request — invalid parameters or business rule violation | | `401` | Unauthorized — missing or expired bearer token | | `403` | Forbidden — valid token but insufficient permissions | | `404` | Not Found — resource does not exist or is not accessible | | `422` | Unprocessable Entity — validation errors on input fields | | `429` | Too Many Requests — rate limit exceeded | | `500` | Internal Server Error — unexpected server error | ## Webhooks Swoogo can send HTTP callbacks when resources are created, updated, or deleted. Configure webhooks via the API or the Swoogo UI. Supported trigger objects: `event`, `contact`, `registrant`, `speaker`, `sponsor`, `session`, `session_attendance`, `registrant_line_item`. Webhook payloads can be sent as `json` (application/json) or `post` (form-encoded). termsOfService: https://www.swoogo.com/terms contact: name: Swoogo Developer Support url: https://developer.swoogo.com email: dev@swoogo.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.swoogo.com/api/v1 description: Production API server - url: https://local.swoogo.com/api/v1 description: Local API server security: [] tags: - name: Authentication description: Obtain and manage OAuth 2.0 bearer tokens for API access. - name: Events description: >- Events are the top-level resource in Swoogo. An event represents a conference, meeting, webinar, or other gathering. Most resources (registrants, sessions, speakers, sponsors) are scoped to an event via `event_id`. Use events to manage scheduling, capacity, registration windows, and event metadata. - name: Registrants description: >- Registrants are individuals who have registered for an event. Each registrant belongs to one event and carries a registration status, package selection, session choices, and financial data (fees, taxes, payments). Registrants can be checked in, emailed, approved/denied, and assigned to groups. - name: Sessions description: >- Sessions are individual agenda items within an event — talks, workshops, panels, or breaks. Sessions have scheduling (date, start/end time, timezone), capacity limits, location assignments, track categorization, and optional fees. Registrants select sessions during registration. - name: Speakers description: >- Speakers are presenters associated with event sessions. Each speaker has profile information (name, bio, company, photo) and can be linked to one or more sessions. - name: Sponsors description: >- Sponsors are organizations or individuals providing support for events. Sponsors have profile data, custom fields, and optional attendance tracking. - name: Contacts description: >- Contacts are people in your Swoogo CRM, independent of any specific event. Contacts can be linked to registrants across multiple events and managed via invitation lists. - name: Registrant Types description: >- Registration types (reg types) define categories of attendees for an event — such as "Attendee", "Exhibitor", or "VIP". Each reg type can have its own capacity, naming, and group size constraints. - name: Packages description: >- Packages define pricing tiers for event registration. A package specifies the fee amount, early bird pricing, and which sessions or features are included. Registrants select a package during registration. - name: Discount Codes description: >- Discount codes provide percentage or absolute discounts on registration fees. Codes can have capacity limits, group size requirements, and apply-to-all or selective targeting. Codes can be cloned to create variants. - name: Transactions description: >- Transactions record financial activity for registrants — payments, refunds, and credits. Supports offline payment types (credit card, wire transfer, check, cash, etc.) and integration with payment gateways. - name: Registrant Sessions description: >- Manage which sessions a registrant is enrolled in. Add or remove session assignments. - name: Registrant Session Waitlists description: >- Manage waitlist entries for sessions that are at capacity. Add or remove waitlist positions. - name: Registrant Groups description: >- Manage group registration assignments. Add or remove registrants from registration groups. - name: Registrant Line Items description: >- View itemized financial line items for registrant orders, including fees, taxes, and discounts. - name: Registrant Line Item Audits description: View the audit trail for changes to registrant line items. - name: Event Fields description: >- Manage custom fields on events. Create, update, and delete event-level custom field definitions. - name: Event Questions description: View event questions configured for registration forms. - name: Event Websites description: View websites associated with events. - name: Event Badges description: Manage event badges. Generate badge PDFs for registrants. - name: Event Folders description: View event folders used to organize events in the Swoogo dashboard. - name: Session Fields description: >- Manage custom fields on sessions. Create, update, and delete session-level custom field definitions. - name: Session Locations description: >- Manage physical or virtual locations where sessions take place. Locations can be assigned to sessions and include name, capacity, and address information. - name: Session Attendance description: Track and manage session attendance records for registrants. - name: Session Scans description: Record and manage check-in scans for session attendance. - name: Session Fees description: Manage pricing for individual sessions, including early bird rates. - name: Package Fees description: Manage pricing for packages, including early bird rates. - name: Tracks description: >- Tracks group related sessions into thematic categories (e.g., "Technical", "Business", "Keynotes"). Registrants can filter sessions by track. - name: Pages description: View pages associated with event websites. - name: Speaker Sessions description: >- Manage the association between speakers and sessions. Assign or remove speakers from sessions. - name: Sponsor Fields description: >- Manage custom fields on sponsors. Create, update, and delete sponsor-level custom field definitions. - name: Sponsor Attendance description: View sponsor attendance records for events. - name: Contact Fields description: View custom field definitions for contacts. - name: Invitation Lists description: >- Invitation lists are curated groups of contacts used for targeted event invitations and access control. Manage lists and their contact memberships. - name: Data Lists description: >- Data lists store reusable sets of key-value options used in custom fields (e.g., dropdown choices, checkbox options). Manage lists and their items. - name: Data List Items description: Manage individual items within a data list. - name: Call for Speaker Contacts description: Manage contacts who have submitted to a call for speakers program. - name: Call for Speaker Reviews description: Manage reviews of call for speaker submissions. - name: Call for Speaker Submissions description: Manage speaker submissions to a call for speakers program. - name: Images description: >- Upload, retrieve, and delete images associated with resources (registrants, speakers, sponsors, etc.). - name: Webhooks description: >- Configure HTTP callbacks that fire when resources are created, updated, or deleted. Webhooks support JSON and form-encoded payloads, custom headers, and retry logic. - name: Webhook Groups description: >- Organize webhooks into groups for easier management. A webhook group contains one or more webhooks that share common configuration. paths: /events/field: post: tags: - Event Fields summary: Create Field description: >- Creates a new custom field definition for events. Specify the field name, type (text, dropdown, checkbox, etc.), visibility, sort order, and choices (for selection-type fields). The field will become available for data entry on events. operationId: createEventField requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: allow_html: type: string example: '' choices: type: string example: '' name: type: string example: '' required: type: string example: '' s_button_text: type: string example: '' s_link_collection_fields: type: string example: '' s_max_links: type: string example: '' s_url_display_format: type: string example: '' s_url_image_id: type: string example: '' sort: type: string example: '' type: type: string example: '' visible: type: string example: '' examples: Create Event Field: value: allow_html: '' choices: '' name: '' required: '' s_button_text: '' s_link_collection_fields: '' s_max_links: '' s_url_display_format: '' s_url_image_id: '' sort: '' type: '' visible: '' responses: '201': description: Create Object content: application/json: schema: type: object properties: created_at: type: string example: '2022-06-26 14:30:00' updated_at: type: string example: '2022-06-26 14:30:00' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: responses: Unauthorized: description: >- Authentication failed. The bearer token is missing, expired, or invalid. Obtain a new token via `POST /oauth2/token`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: name: Unauthorized message: Your request was made with invalid credentials. code: 0 status: 401 Forbidden: description: >- The authenticated user does not have permission to access this resource. This can occur if the resource belongs to a different account or the API credentials lack the required scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: name: Forbidden message: You do not have access to that resource. code: 0 status: 403 NotFound: description: >- The specified resource does not exist or has been deleted. Verify the ID is correct and that the resource belongs to an event your credentials have access to. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: name: Not Found message: The requested resource does not exist. code: 0 status: 404 InternalServerError: description: >- An unexpected server error occurred. If this persists, contact Swoogo support with the request details and timestamp. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: name: Internal Server Error message: An error occurred while processing your request. code: 0 status: 500 schemas: ErrorResponse: type: object description: Standard error response returned for all 4xx and 5xx status codes. properties: name: type: string description: >- Human-readable error type name (e.g., "Unauthorized", "Forbidden", "Not Found"). example: Unauthorized message: type: string description: Detailed error message explaining what went wrong. example: Your request was made with invalid credentials. code: type: integer description: >- Application-specific error code. Currently `0` for all standard errors. example: 0 status: type: integer description: HTTP status code of the error response. example: 401 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: access_token description: >- OAuth 2.0 bearer token obtained from `POST /oauth2/token`. Tokens expire after 30 minutes. Include in the `Authorization` header as `Bearer {access_token}`. ````