openapi: 3.0.3
info:
  title: Neon CRM API v2 Accounts Volunteers API
  description: Neon CRM API v2 is a RESTful, JSON-based rebuild of Neon One's legacy API v1, first launched in 2019. It exposes constituent accounts, households, donations, pledges, recurring donations, campaigns, memberships, events, custom fields and custom objects, orders and the online store, volunteers, and webhook subscriptions. All requests use HTTP Basic Authentication with the organization's Org ID as the username and an API key as the password. Neon CRM API v1 and its legacy webhook structure are scheduled to be retired on July 11, 2026; this document covers API v2 only. This is a representative subset of the full v2 surface, grounded in Neon's public developer documentation and version release notes (v2.0 - v2.11), not an exhaustive mirror of every documented endpoint.
  version: '2.11'
  contact:
    name: Neon One Developer Center
    url: https://developer.neoncrm.com/
  license:
    name: Proprietary
    url: https://neonone.com/
servers:
- url: https://api.neoncrm.com/v2
  description: Production and Sandbox
- url: https://trial.z2systems.com/v2
  description: Trial instances
security:
- basicAuth: []
tags:
- name: Volunteers
  description: Volunteers, groups, opportunities, roles, shifts, and time sheets.
paths:
  /volunteers:
    get:
      operationId: listVolunteers
      tags:
      - Volunteers
      summary: List volunteers
      description: Volunteer Management endpoints added to API v2.9 in November 2024.
      responses:
        '200':
          description: A list of volunteers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Volunteer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /opportunities:
    get:
      operationId: listVolunteerOpportunities
      tags:
      - Volunteers
      summary: List volunteer opportunities
      responses:
        '200':
          description: A list of volunteer opportunities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VolunteerOpportunity'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createVolunteerOpportunity
      tags:
      - Volunteers
      summary: Create a volunteer opportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolunteerOpportunity'
      responses:
        '200':
          description: The created opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerOpportunity'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /opportunities/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the volunteer opportunity.
      schema:
        type: string
    get:
      operationId: getVolunteerOpportunity
      tags:
      - Volunteers
      summary: Retrieve a volunteer opportunity
      responses:
        '200':
          description: The requested opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerOpportunity'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateVolunteerOpportunity
      tags:
      - Volunteers
      summary: Update a volunteer opportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolunteerOpportunity'
      responses:
        '200':
          description: The updated opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerOpportunity'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchVolunteerOpportunity
      tags:
      - Volunteers
      summary: Partially update a volunteer opportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerOpportunity'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVolunteerOpportunity
      tags:
      - Volunteers
      summary: Delete a volunteer opportunity
      responses:
        '200':
          description: Deletion confirmation.
        '404':
          $ref: '#/components/responses/NotFound'
  /opportunities/{id}/addVolunteers:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the volunteer opportunity.
      schema:
        type: string
    post:
      operationId: addVolunteersToOpportunity
      tags:
      - Volunteers
      summary: Add volunteers to an opportunity
      description: Accepts the opportunityRoles parameter, added in API v2.11, to assign a role during sign-up.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                volunteerIds:
                  type: array
                  items:
                    type: string
                opportunityRoles:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Assignment result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /opportunities/{opportunityId}/shifts:
    parameters:
    - name: opportunityId
      in: path
      required: true
      description: The ID of the volunteer opportunity.
      schema:
        type: string
    get:
      operationId: listOpportunityShifts
      tags:
      - Volunteers
      summary: List shifts for a volunteer opportunity
      responses:
        '200':
          description: A list of shifts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VolunteerShift'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOpportunityShift
      tags:
      - Volunteers
      summary: Create a shift for a volunteer opportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolunteerShift'
      responses:
        '200':
          description: The created shift.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolunteerShift'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /timesheets:
    get:
      operationId: listTimeSheets
      tags:
      - Volunteers
      summary: List volunteer time sheets
      responses:
        '200':
          description: A list of time sheets.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTimeSheet
      tags:
      - Volunteers
      summary: Create a volunteer time sheet entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The created time sheet entry.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /timesheets/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the time sheet entry.
      schema:
        type: string
    get:
      operationId: getTimeSheet
      tags:
      - Volunteers
      summary: Retrieve a volunteer time sheet entry
      responses:
        '200':
          description: The requested time sheet entry.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTimeSheet
      tags:
      - Volunteers
      summary: Delete a volunteer time sheet entry
      responses:
        '200':
          description: Deletion confirmation.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    VolunteerOpportunity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
      additionalProperties: true
    VolunteerShift:
      type: object
      properties:
        id:
          type: string
        opportunityId:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
      additionalProperties: true
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    Volunteer:
      type: object
      properties:
        id:
          type: string
        accountId:
          type: string
        skills:
          type: array
          items:
            type: string
      additionalProperties: true
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid Org ID / API key in the Basic Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication. Username is the Neon CRM organization's Org ID; password is an API key generated for a system user under Settings > User Management.