openapi: 3.2.0
info:
  title: Popp Custom Fields (Beta) API
  description: Popp API documentation
  version: '1'
servers:
- url: https://api.joinpopp.com
  description: Development server
security:
- popp_api_key: []
  organization_id: []
tags:
- name: Custom Fields (Beta)
paths:
  /v1/custom-fields:
    post:
      summary: Create a custom field (Beta)
      description: '**Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release.


        Creates a custom field for your organization. The field is scoped to the organization resolved from your API key; any `organizationId` in the body is ignored. `fieldKey` must be unique among your active fields, and `type` is fixed once created. When `hasFixedOptions` is true, `allowedValues` is required and non-empty; when false, `allowedValues` must be empty or omitted. `displayAs: AGE` shows a `DATE` field as an age; it is rejected on any other type, and omitting it defaults to `DATE`.


        **Capacity:** there is a maximum number of fields per `type`, and deleting a field does not free that capacity (deletes are permanent). Provision fields deliberately. A create that exceeds the limit for a type returns 400.'
      operationId: create-custom-field
      parameters: []
      tags:
      - Custom Fields (Beta)
      requestBody:
        description: The custom field to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomFieldRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
    get:
      summary: List custom fields (Beta)
      description: '**Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release.


        Lists the active custom fields in your organization. Retired (deleted) fields are not returned. Results are paginated; pass the returned `nextToken` to fetch the next page.'
      operationId: list-custom-fields
      parameters:
      - name: limit
        in: query
        description: Maximum number of fields to return (1-50, default 20).
        required: false
        schema:
          $ref: '#/components/schemas/limit'
      - name: nextToken
        in: query
        description: Pagination token from a previous response.
        required: false
        schema:
          $ref: '#/components/schemas/nextToken'
      tags:
      - Custom Fields (Beta)
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomFieldsResponse'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
  /v1/custom-fields/{id}:
    get:
      summary: Get a custom field (Beta)
      description: '**Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release.


        Returns a single custom field by id. A field that belongs to a different organization, or one that has been deleted, returns 404.'
      operationId: get-custom-field
      parameters:
      - name: id
        in: path
        description: Custom field id (UUID).
        required: true
        schema:
          $ref: '#/components/schemas/id'
      tags:
      - Custom Fields (Beta)
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
    patch:
      summary: Update a custom field (Beta)
      description: '**Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release.


        Updates a custom field''s `label`, `hasFixedOptions`, `allowedValues` and/or `displayAs`. At least one field must be provided. `type` is immutable and cannot be changed. `hasFixedOptions` and `allowedValues` must stay consistent (a fixed-options field needs non-empty `allowedValues`; a free-input field must have none), and `displayAs: AGE` is only valid on a `DATE` field. A field belonging to another organization, or one that has been deleted, returns 404.'
      operationId: update-custom-field
      parameters:
      - name: id
        in: path
        description: Custom field id (UUID).
        required: true
        schema:
          $ref: '#/components/schemas/id'
      tags:
      - Custom Fields (Beta)
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomFieldRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
    delete:
      summary: Delete a custom field (Beta)
      description: '**Beta.** You can define and manage custom fields now. Populating candidate values and filtering or searching by them arrives in a later release.


        Deletes a custom field. **Deletion is permanent and does not free the field''s capacity for its type** (the slot is retired, not reused), so delete deliberately. After deletion the field no longer appears in the list and returns 404 on subsequent reads. A field belonging to another organization, or one already deleted, returns 404.'
      operationId: delete-custom-field
      parameters:
      - name: id
        in: path
        description: Custom field id (UUID).
        required: true
        schema:
          $ref: '#/components/schemas/id'
      tags:
      - Custom Fields (Beta)
      responses:
        '204':
          description: ''
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
components:
  schemas:
    CreateCustomFieldRequest:
      type: object
      description: Request body for creating a custom field.
      properties:
        fieldKey:
          type: string
          minLength: 1
          maxLength: 255
          title: Field Key
          description: Your stable key for the field. Must be unique among the organization's active fields.
        label:
          type: string
          minLength: 1
          maxLength: 255
          title: Label
          description: Human-readable display name for the field.
        type:
          type: string
          enum:
          - TEXT
          - TEXT_ARRAY
          - NUMBER
          - DATE
          - BOOLEAN
          title: Type
          description: The field's data type. Cannot be changed after creation.
        hasFixedOptions:
          type: boolean
          title: Has Fixed Options
          description: When true, `allowedValues` is required and non-empty (a dropdown). When false, `allowedValues` must be empty or omitted.
        allowedValues:
          type: array
          items:
            type: string
            minLength: 1
          title: Allowed Values
          description: The permitted values. Required and non-empty when `hasFixedOptions` is true; must be empty or omitted otherwise.
        displayAs:
          type: string
          enum:
          - DATE
          - AGE
          title: Display As
          description: How the value is displayed. `AGE` shows a `DATE` field as a whole-number age in years, derived from the stored date on the day it is read; it is rejected on any other type. Defaults to `DATE`.
      required:
      - fieldKey
      - label
      - type
      - hasFixedOptions
      additionalProperties: false
    ListCustomFieldsResponse:
      type: object
      properties:
        items:
          type: array
          description: Active custom fields in the caller's organization.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              organizationId:
                type: string
                format: uuid
              fieldKey:
                type: string
              label:
                type: string
              type:
                type: string
                enum:
                - TEXT
                - TEXT_ARRAY
                - NUMBER
                - DATE
                - BOOLEAN
              hasFixedOptions:
                type: boolean
              allowedValues:
                type:
                - array
                - 'null'
                items:
                  type: string
              displayAs:
                type: string
                enum:
                - DATE
                - AGE
              createdAt:
                type: string
                format: date-time
              updatedAt:
                type: string
                format: date-time
            required:
            - id
            - organizationId
            - fieldKey
            - label
            - type
            - hasFixedOptions
            - allowedValues
            - displayAs
            - createdAt
            - updatedAt
            additionalProperties: false
        nextToken:
          type:
          - string
          - 'null'
          description: Pass back as `nextToken` to fetch the next page. Null when there are no more results.
      required:
      - items
      - nextToken
      additionalProperties: false
    UpdateCustomFieldRequest:
      type: object
      description: Request body for updating a custom field. At least one field must be provided. `type` is immutable and cannot be updated.
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 255
          title: Label
          description: New display name for the field.
        hasFixedOptions:
          type: boolean
          title: Has Fixed Options
          description: Whether values are constrained to `allowedValues`. Must stay consistent with `allowedValues`.
        allowedValues:
          type: array
          items:
            type: string
            minLength: 1
          title: Allowed Values
          description: The permitted values. Must be non-empty when `hasFixedOptions` is true and empty otherwise.
        displayAs:
          type: string
          enum:
          - DATE
          - AGE
          title: Display As
          description: How the value is displayed. `AGE` is only valid on a `DATE` field. Omit to leave unchanged.
      additionalProperties: false
    nextToken:
      type: string
    limit:
      type: integer
    ErrorResponse:
      type: object
    id:
      type: string
    CustomField:
      type: object
      description: A custom field definition for an organization. Custom fields let you add your own typed, filterable attributes to candidate profiles.
      properties:
        id:
          type: string
          format: uuid
          title: Field ID
          description: Unique identifier for the custom field.
        organizationId:
          type: string
          format: uuid
          title: Organization ID
          description: The organization the field belongs to.
        fieldKey:
          type: string
          title: Field Key
          description: Your stable key for the field, unique among the organization's active fields (e.g. "clearanceLevel").
        label:
          type: string
          title: Label
          description: Human-readable display name for the field.
        type:
          type: string
          enum:
          - TEXT
          - TEXT_ARRAY
          - NUMBER
          - DATE
          - BOOLEAN
          title: Type
          description: The field's data type. Immutable after creation.
        hasFixedOptions:
          type: boolean
          title: Has Fixed Options
          description: When true, values are constrained to `allowedValues` (a dropdown). When false, the field accepts free input.
        allowedValues:
          type:
          - array
          - 'null'
          title: Allowed Values
          description: The permitted values when `hasFixedOptions` is true; null or omitted otherwise.
          items:
            type: string
        displayAs:
          type: string
          enum:
          - DATE
          - AGE
          title: Display As
          description: How the value is displayed. `AGE` shows a `DATE` field as a whole-number age in years; the stored value is still the date. `DATE` for every other field.
        createdAt:
          type: string
          format: date-time
          title: Created At
          description: When the field was created (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          title: Updated At
          description: When the field was last updated (ISO 8601).
      required:
      - id
      - organizationId
      - fieldKey
      - label
      - type
      - hasFixedOptions
      - allowedValues
      - displayAs
      - createdAt
      - updatedAt
      additionalProperties: false
  securitySchemes:
    popp_api_key:
      description: Your Popp API key for authentication
      type: apiKey
      name: x-api-key
      in: header
    organization_id:
      description: Your organization's unique identifier
      type: apiKey
      name: x-organization-id
      in: header
x-provenance:
  method: searched
  source: https://docs.joinpopp.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.joinpopp.com/reference/add-candidates-to-list-by-external-id.md
  - https://docs.joinpopp.com/reference/add-candidates-to-list.md
  - https://docs.joinpopp.com/reference/archive-analysis.md
  - https://docs.joinpopp.com/reference/archive-document-type.md
  - https://docs.joinpopp.com/reference/archive-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/archive-workflow.md
  - https://docs.joinpopp.com/reference/bulk-create-conversations.md
  - https://docs.joinpopp.com/reference/cancel-booking.md
  - https://docs.joinpopp.com/reference/cancel-workflow-run.md
  - https://docs.joinpopp.com/reference/create-analysis-candidate.md
  - https://docs.joinpopp.com/reference/create-analysis.md
  - https://docs.joinpopp.com/reference/create-campaign.md
  - https://docs.joinpopp.com/reference/create-candidate-list.md
  - https://docs.joinpopp.com/reference/create-candidate-note-by-external-id.md
  - https://docs.joinpopp.com/reference/create-candidate-note.md
  - https://docs.joinpopp.com/reference/create-candidate.md
  - https://docs.joinpopp.com/reference/create-conversation.md
  - https://docs.joinpopp.com/reference/create-custom-field.md
  - https://docs.joinpopp.com/reference/create-document-credential.md
  - https://docs.joinpopp.com/reference/create-document-type.md
  - https://docs.joinpopp.com/reference/create-meeting-template.md
  - https://docs.joinpopp.com/reference/create-organization-config.md
  - https://docs.joinpopp.com/reference/create-scheduling-conversation.md
  - https://docs.joinpopp.com/reference/create-user.md
  - https://docs.joinpopp.com/reference/create-webhook.md
  - https://docs.joinpopp.com/reference/create-workflow.md
  - https://docs.joinpopp.com/reference/deactivate-user-by-email.md
  - https://docs.joinpopp.com/reference/deactivate-user.md
  - https://docs.joinpopp.com/reference/delete-candidate-by-email.md
  - https://docs.joinpopp.com/reference/delete-candidate-by-external-id.md
  - https://docs.joinpopp.com/reference/delete-candidate-by-phone-number.md
  - https://docs.joinpopp.com/reference/delete-candidate-list-by-external-id.md
  - https://docs.joinpopp.com/reference/delete-candidate-list.md
  - https://docs.joinpopp.com/reference/delete-candidate-note.md
  - https://docs.joinpopp.com/reference/delete-candidate.md
  - https://docs.joinpopp.com/reference/delete-custom-field.md
  - https://docs.joinpopp.com/reference/delete-document-credential.md
  - https://docs.joinpopp.com/reference/delete-document-type.md
  - https://docs.joinpopp.com/reference/delete-meeting-template.md
  - https://docs.joinpopp.com/reference/delete-tag.md
  - https://docs.joinpopp.com/reference/delete-user-by-email.md
  - https://docs.joinpopp.com/reference/delete-user.md
  - https://docs.joinpopp.com/reference/delete-webhook.md
  - https://docs.joinpopp.com/reference/download-media.md
  - https://docs.joinpopp.com/reference/generate-preferred-answer-requirements.md
  - https://docs.joinpopp.com/reference/generate-questions.md
  - https://docs.joinpopp.com/reference/generate-requirements.md
  - https://docs.joinpopp.com/reference/get-analysis.md
  - https://docs.joinpopp.com/reference/get-booking.md
  - https://docs.joinpopp.com/reference/get-campaign.md
  - https://docs.joinpopp.com/reference/get-candidate-by-external-id.md
  - https://docs.joinpopp.com/reference/get-candidate-list-by-external-id.md
  - https://docs.joinpopp.com/reference/get-candidate-list.md
  - https://docs.joinpopp.com/reference/get-candidate-profile-by-external-id.md
  - https://docs.joinpopp.com/reference/get-candidate.md
  - https://docs.joinpopp.com/reference/get-conversation.md
  - https://docs.joinpopp.com/reference/get-custom-field.md
  - https://docs.joinpopp.com/reference/get-document-media.md
  - https://docs.joinpopp.com/reference/get-document-type.md
  - https://docs.joinpopp.com/reference/get-document.md
  - https://docs.joinpopp.com/reference/get-meeting-template.md
  - https://docs.joinpopp.com/reference/get-organization-config-by-external-id.md
  - https://docs.joinpopp.com/reference/get-organization-config.md
  - https://docs.joinpopp.com/reference/get-organization-details.md
  - https://docs.joinpopp.com/reference/get-user-by-email.md
  - https://docs.joinpopp.com/reference/get-user-calendar.md
  - https://docs.joinpopp.com/reference/get-user.md
  - https://docs.joinpopp.com/reference/get-workflow-analysis-application.md
  - https://docs.joinpopp.com/reference/get-workflow-analysis.md
  - https://docs.joinpopp.com/reference/get-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/get-workflow-run.md
  - https://docs.joinpopp.com/reference/get-workflow.md
  - https://docs.joinpopp.com/reference/hand-conversation-to-agent.md
  - https://docs.joinpopp.com/reference/invite-calendar-contact.md
  - https://docs.joinpopp.com/reference/list-agents.md
  - https://docs.joinpopp.com/reference/list-analyses.md
  - https://docs.joinpopp.com/reference/list-ats-job-stages.md
  - https://docs.joinpopp.com/reference/list-ats-jobs.md
  - https://docs.joinpopp.com/reference/list-ats-rejection-reasons.md
  - https://docs.joinpopp.com/reference/list-bookings.md
  - https://docs.joinpopp.com/reference/list-campaigns.md
  - https://docs.joinpopp.com/reference/list-candidate-lists.md
  - https://docs.joinpopp.com/reference/list-candidate-notes-by-external-id.md
  - https://docs.joinpopp.com/reference/list-candidate-notes.md
  - https://docs.joinpopp.com/reference/list-conversation-documents.md
  - https://docs.joinpopp.com/reference/list-conversation-messages.md
  - https://docs.joinpopp.com/reference/list-conversations.md
  - https://docs.joinpopp.com/reference/list-custom-fields.md
  - https://docs.joinpopp.com/reference/list-document-credentials.md
  - https://docs.joinpopp.com/reference/list-document-types.md
  - https://docs.joinpopp.com/reference/list-meeting-templates.md
  - https://docs.joinpopp.com/reference/list-organization-users.md
  - https://docs.joinpopp.com/reference/list-organizations.md
  - https://docs.joinpopp.com/reference/list-tags.md
  - https://docs.joinpopp.com/reference/list-templates.md
  - https://docs.joinpopp.com/reference/list-user-calendars.md
  - https://docs.joinpopp.com/reference/list-users.md
  - https://docs.joinpopp.com/reference/list-webhook-events.md
  - https://docs.joinpopp.com/reference/list-webhooks.md
  - https://docs.joinpopp.com/reference/list-workflow-analysis-application-history.md
  - https://docs.joinpopp.com/reference/list-workflow-analysis-applications.md
  - https://docs.joinpopp.com/reference/list-workflow-runs.md
  - https://docs.joinpopp.com/reference/list-workflows.md
  - https://docs.joinpopp.com/reference/parse-availability.md
  - https://docs.joinpopp.com/reference/pause-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/pause-workflow.md
  - https://docs.joinpopp.com/reference/process-document.md
  - https://docs.joinpopp.com/reference/publish-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/publish-workflow.md
  - https://docs.joinpopp.com/reference/reactivate-user-by-email.md
  - https://docs.joinpopp.com/reference/reactivate-user.md
  - https://docs.joinpopp.com/reference/remove-candidate-document-by-external-id.md
  - https://docs.joinpopp.com/reference/remove-candidate-document.md
  - https://docs.joinpopp.com/reference/remove-candidates-from-list-by-external-id.md
  - https://docs.joinpopp.com/reference/remove-candidates-from-list.md
  - https://docs.joinpopp.com/reference/reparse-candidate-cv-by-external-id.md
  - https://docs.joinpopp.com/reference/reparse-candidate-cv.md
  - https://docs.joinpopp.com/reference/resend-booking-url.md
  - https://docs.joinpopp.com/reference/resume-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/resume-workflow.md
  - https://docs.joinpopp.com/reference/send-conversation-message.md
  - https://docs.joinpopp.com/reference/set-user-calendar-availability.md
  - https://docs.joinpopp.com/reference/sign-out-user-by-email.md
  - https://docs.joinpopp.com/reference/sign-out-user.md
  - https://docs.joinpopp.com/reference/start-workflow-runs-by-external-id.md
  - https://docs.joinpopp.com/reference/start-workflow-runs.md
  - https://docs.joinpopp.com/reference/stop-campaign.md
  - https://docs.joinpopp.com/reference/takeover-conversation.md
  - https://docs.joinpopp.com/reference/update-analysis.md
  - https://docs.joinpopp.com/reference/update-booking.md
  - https://docs.joinpopp.com/reference/update-campaign.md
  - https://docs.joinpopp.com/reference/update-candidate-by-external-id.md
  - https://docs.joinpopp.com/reference/update-candidate-list-by-external-id.md
  - https://docs.joinpopp.com/reference/update-candidate-list.md
  - https://docs.joinpopp.com/reference/update-candidate-note.md
  - https://docs.joinpopp.com/reference/update-candidate.md
  - https://docs.joinpopp.com/reference/update-custom-field.md
  - https://docs.joinpopp.com/reference/update-document-credential.md
  - https://docs.joinpopp.com/reference/update-document-type.md
  - https://docs.joinpopp.com/reference/update-meeting-template.md
  - https://docs.joinpopp.com/reference/update-organization-config-by-external-id.md
  - https://docs.joinpopp.com/reference/update-organization-config.md
  - https://docs.joinpopp.com/reference/update-organization-details.md
  - https://docs.joinpopp.com/reference/update-requirements-and-reanalyse.md
  - https://docs.joinpopp.com/reference/update-user-by-email.md
  - https://docs.joinpopp.com/reference/update-user.md
  - https://docs.joinpopp.com/reference/update-webhook.md
  - https://docs.joinpopp.com/reference/update-workflow-by-external-id.md
  - https://docs.joinpopp.com/reference/update-workflow.md
  merge:
    pages: 149
    deduped: 618
    conflicts_kept_first: 0