openapi: 3.1.0
info:
  title: Groundswell API
  version: "1.0"
  description: |
    The Groundswell API lets you download your company's reports and manage employees through SCIM.

    ## Authentication

    Every request is authenticated with your Groundswell API key, sent as a bearer token in the `Authorization` header:

    ```
    Authorization: Bearer YOUR_SECRET_TOKEN
    ```

    To get an API key, reach out to our customer support team.

    ## Errors

    Report endpoints return errors as JSON with a `message` and a `code`, for example:

    ```json
    { "message": "UnauthorizedError", "code": "UNAUTHORIZED" }
    ```

    SCIM endpoints return errors in the [SCIM error format](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12).

    ## OpenAPI description

    This reference is built from an OpenAPI description that you can import into Postman, Insomnia or other API tools: [developers.groundswell.io/openapi.yaml](https://developers.groundswell.io/openapi.yaml).
servers:
  - url: https://api.groundswell.io
security:
  - apiKey: []
tags:
  - name: Reports
    description: |
      This is a collection of reports that can be accessed using the Groundswell API key.

      By default, all report endpoints return the data as an attached CSV file. If you want to receive the data as a JSON array instead, set the `Accept` header to exactly `application/json`. The **Volunteer events** report is the exception: it returns JSON by default.

      To get an API key, reach out to our customer support team.

      ## Additional field filtering

      The **Volunteer hours** report supports optional filtering by additional field. If your company has additional fields enabled, set the `value` query param to the additional field value you want, for example `value=accounting`.
  - name: SCIM
    description: |
      This is the current Groundswell SCIM implementation.

      As of now, only managing employees through the `Users` endpoints is supported. Requests are authenticated using your API key, the same one used for reports. To get an API key, reach out to our customer support team.

      ## Introspection

      The `Schemas`, `ResourceTypes` and `ServiceProviderConfig` endpoints can be used to get details on our SCIM implementation. Like every other request, they require your API key.

      ## Users

      These are the endpoints used to manage employees in your company.

      - `id` is Groundswell's ID for the employee. Use it in the `/Users/{id}` endpoints.
      - `userName` is the employee ID in your company. To find an employee by it, use `filter=userName eq "<employee ID>"`.
      - The employee's email is the `emails` entry with `primary: true`.
      - `active` sets the employee status: `true` for active, `false` for terminated.

      Additional fields are set in the `additionalFields` attribute, mapping the additional field name to the employee's value, for example `{ "location": "New York", "businessUnit": "Finance" }`. The supported names are `location`, `jobTier`, `businessUnit`, `department`, `workCity`, `workState`, `workCountryCode` and `customField_1` to `customField_4`, and each one must be configured for your company. An empty or `null` value clears the field.

      Employee language can be set in `preferredLanguage` to one of the following options (defaults to English if not set):

      | Language | Value |
      | --- | --- |
      | English | `en` |
      | Spanish | `es` |
      | Portuguese | `pt` |
      | Portuguese (Brazil) | `pt_BR` |
      | Simplified Chinese | `zh_CN` |
      | Traditional Chinese | `zh_TW` |
      | German | `de` |
      | Korean | `ko` |
      | Italian | `it` |
      | Dutch | `nl` |
      | Japanese | `ja` |
      | Vietnamese | `vi` |
      | Thai | `th` |
      | French | `fr` |
      | Turkish | `tr` |
      | Luxembourgish | `lb` |
      | Malay | `ms` |
      | Indonesian | `id` |
paths:
  /v1/corporation/download-impact-report:
    get:
      tags:
        - Reports
      operationId: getDonationsReport
      summary: Donations
      description: |
        This report is a list of all donations made by employees, including matches, with the nonprofit that received each one. If additional fields are enabled, they will be included in it.
      parameters:
        - $ref: "#/components/parameters/Accept"
      responses:
        "200":
          description: The donations report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - donationId: cltb2v1kq000a08l4b9xq7h2m
                  donationDate: "2024-03-05"
                  amount: "20.20"
                  npoId: cl8m2x4tq00051dl8f3k0a9zr
                  npoName: Conservation International Foundation
                  npoCity: ARLINGTON
                  npoState: VA
                  npoZip: 22202-3715
                  npoCountry: US
                  npoEin: "'521497470'"
                  npoDba: ""
                  issueAreas: Environment
                  nteeCode: C30Z
                  nteeDescription: ""
                  donationType: Employee
                  distributionPartner: PayPal grants
                  distributionMethod: Electronic transfer
                  distributionStatus: Funds received
                  distributionDate: "2024-03-20"
                  department: Accounting
                  location: New York
                - donationId: cltb2v1kq000b08l4c2rw5n8p
                  donationDate: "2024-03-05"
                  amount: "20.20"
                  npoId: cl8m2x4tq00051dl8f3k0a9zr
                  npoName: Conservation International Foundation
                  npoCity: ARLINGTON
                  npoState: VA
                  npoZip: 22202-3715
                  npoCountry: US
                  npoEin: "'521497470'"
                  npoDba: ""
                  issueAreas: Environment
                  nteeCode: C30Z
                  nteeDescription: ""
                  donationType: Match
                  distributionPartner: ""
                  distributionMethod: ""
                  distributionStatus: Pending
                  distributionDate: ""
                  programName: 2024 Matching Gift Program
                  department: Accounting
                  location: New York
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/corporation/download-employee-donations-report:
    get:
      tags:
        - Reports
      operationId: getEmployeeDonationsReport
      summary: Employee donations
      description: |
        This report is a list of employee donations, not including information about the destination of such donations.
      parameters:
        - $ref: "#/components/parameters/Accept"
      responses:
        "200":
          description: The employee donations report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - id: cltb2v1kq000a08l4b9xq7h2m
                  donationDate: 03/05/24
                  amount: "20.20"
                  employeeId: georgiewash
                  distributionPartner: PayPal grants
                  distributionMethod: Electronic transfer
                  distributionStatus: Funds received
                - id: cltb2qz7e000708l4h6tk1c3d
                  donationDate: 03/04/24
                  amount: "10.10"
                  employeeId: georgiewash
                  distributionPartner: ""
                  distributionMethod: ""
                  distributionStatus: Pending
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/corporation/download-corporate-grants:
    get:
      tags:
        - Reports
      operationId: getGrantPaymentsReport
      summary: Grant Payments Report
      description: |
        Returns all grant payments for your company. Same data as the CSV download in **Grants > Payments**. By default the data comes as an attached CSV file. Set the `Accept` header to `application/json` to get JSON.

        Fields:

        - `paymentDate`: date of the payment, MM/DD/YYYY
        - `recipient`: NPO or applicant name
        - `recipientCity`, `recipientState`, `recipientCountry`
        - `amount`: formatted string, for example `"$25,000"`
        - `status`: `PROCESSING`, `SENT`, `FUNDED`, `RETURNED` or `BLOCKED`
        - `type`: see below
        - one `tag_<id>` column per company tag (BU, Fiscal year, etc.)
        - `internalNote`
        - `noteForNpo`

        Type:

        - `DIRECT`: paid on the platform, not linked to a grant program
        - `PROGRAM`: paid on the platform through a grant program application
        - `PROGRAM OUTSIDE`: paid outside the platform, linked to a grant program application
        - `OUTSIDE`: paid outside the platform, not linked to a program
        - `IMPORT`: imported historical data
        - `VOLUNTEER`: volunteer event grant
        - `FUNDRAISER`: linked to a fundraiser
      parameters:
        - $ref: "#/components/parameters/Accept"
      responses:
        "200":
          description: The grant payments report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - paymentDate: 07/02/2026
                  recipient: Charity Water
                  recipientCity: Franklin
                  recipientState: TN
                  recipientCountry: US
                  amount: $25,000
                  status: PROCESSING
                  type: PROGRAM
                  tag_cm3k2j1h4g5f6d7s8a9q0w1e: Community Health
                  internalNote: ""
                  noteForNpo: 2026 CBC Cares Grant Application
                - paymentDate: 06/26/2026
                  recipient: Families Forward
                  recipientCity: Irvine
                  recipientState: CA
                  recipientCountry: US
                  amount: $25,000
                  status: FUNDED
                  type: PROGRAM OUTSIDE
                  tag_cm3k2j1h4g5f6d7s8a9q0w1e: Community Health
                  internalNote: Paid by AP team
                  noteForNpo: sponsorship table at gala
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/corporation/download-enrollment-report:
    get:
      tags:
        - Reports
      operationId: getEnrollmentReport
      summary: Enrollment
      description: |
        Contains data about the enrollment of employees, alongside engagement data, such as if the employee has contributed or donated.

        Terminated employees are left out unless you set `includeTerminated=true`.
      parameters:
        - $ref: "#/components/parameters/Accept"
        - name: includeTerminated
          in: query
          required: false
          description: Set to `true` to include terminated employees. Leave it out to only get current employees.
          schema:
            type: boolean
      responses:
        "200":
          description: The enrollment report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - id: georgiewash
                  firstName: George
                  lastName: Washington
                  email: george.washington@example.com
                  inviteStatus: Enrolled
                  status: Active
                  added: 08/11/25
                  invited: 08/11/25
                  enrolled: 08/11/25
                  department: n/a
                  businessUnit: n/a
                  jobTier: n/a
                  location: n/a
                  workCity: New York
                  workState: NY
                  workCountryCode: US
                  customField_1: L
                  customField_2: Blue
                  customField_3: n/a
                  customField_4: n/a
                  recurringContributionsCount: 1
                  recurringDonationsCount: 1
                  contributed: false
                  donated: true
                  mostRecentDonation: 08/11/25
                  volunteeredAtLeastOnce: true
                  mostRecentIndividualVolunteerHour: 08/11/25
                  attendedAtLeastOneVolunteerEvent: true
                  mostRecentVolunteerEventHour: 08/11/25
                - id: "35"
                  firstName: John F.
                  lastName: Kennedy
                  email: john.kennedy@example.com
                  inviteStatus: Enrolled
                  status: Active
                  added: 08/11/25
                  invited: 08/11/25
                  enrolled: 08/11/25
                  department: n/a
                  businessUnit: n/a
                  jobTier: n/a
                  location: n/a
                  workCity: Los Angeles
                  workState: CA
                  workCountryCode: US
                  customField_1: M
                  customField_2: Blue
                  customField_3: n/a
                  customField_4: n/a
                  recurringContributionsCount: n/a
                  recurringDonationsCount: n/a
                  contributed: false
                  donated: false
                  mostRecentDonation: n/a
                  volunteeredAtLeastOnce: false
                  mostRecentIndividualVolunteerHour: n/a
                  attendedAtLeastOneVolunteerEvent: false
                  mostRecentVolunteerEventHour: n/a
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/corporation/download-volunteer-hours-report:
    get:
      tags:
        - Reports
      operationId: getVolunteerHoursReport
      summary: Volunteer hours
      description: |
        List of volunteer hours logged for employees or their guests, including relevant information about the volunteer, the event and the supported NPO.

        Can be filtered by additional field value with the `value` query param.
      parameters:
        - $ref: "#/components/parameters/Accept"
        - name: value
          in: query
          required: false
          description: Only include hours from employees with an additional field set to this value, for example `accounting`.
          schema:
            type: string
      responses:
        "200":
          description: The volunteer hours report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - id: cm5gx4c8k0007otm6ah2b6f1d
                  volunteerDate: 05/05/22
                  submittedDate: 05/06/22
                  employeeId: georgiewash
                  volunteerType: Employee
                  firstName: George
                  lastName: Washington
                  department: n/a
                  businessUnit: n/a
                  jobTier: n/a
                  location: n/a
                  workCity: Los Angeles
                  workState: CA
                  workCountryCode: US
                  volunteerHours: 5
                  vtoHours: n/a
                  vtoHoursLoggedToHris: n/a
                  volunteerOrganization: PAWS NY
                  charityId: cl3f8w2d10004pq9s6v1x7k2j
                  ein: "800233785"
                  nteeCode: D20
                  charityState: NY
                  irsDescription: Pets Are Wonderful Support (PAWS) NY provides services to vulnerable New Yorkers who need support caring for their pets due to physical and financial obstacles they face, with particular emphasis on low-income older adults and individuals living with illness or disability.
                  hoursType: Event
                  groundswellIssueAreas: Animals
                  volunteerStatus: Approved
                  matchAmount: "50"
                  matchStatus: Matched
                  eventId: cm5gx3zuw1zeotm6dt3ku3lil
                - volunteerDate: 05/05/22
                  employeeId: georgiewash
                  volunteerOrganization: PAWS NY
                  charityId: cl3f8w2d10004pq9s6v1x7k2j
                  ein: "800233785"
                  nteeCode: D20
                  charityState: NY
                  irsDescription: Pets Are Wonderful Support (PAWS) NY provides services to vulnerable New Yorkers who need support caring for their pets due to physical and financial obstacles they face, with particular emphasis on low-income older adults and individuals living with illness or disability.
                  hoursType: Event
                  groundswellIssueAreas: Animals
                  volunteerStatus: Approved
                  eventId: cm5gx3zuw1zeotm6dt3ku3lil
                  id: cm5gx4dq20009otm6f3w8e5n7
                  submittedDate: 05/06/22
                  volunteerType: Guest
                  firstName: John
                  lastName: Adams
                  department: n/a
                  businessUnit: n/a
                  jobTier: n/a
                  location: n/a
                  workCity: n/a
                  workState: n/a
                  workCountryCode: n/a
                  volunteerHours: 5
                  vtoHours: n/a
                  vtoHoursLoggedToHris: n/a
                  matchAmount: n/a
                  matchStatus: n/a
                - id: clh7q2m9v0012ab34cd56ef78
                  volunteerDate: 05/19/23
                  submittedDate: 05/19/23
                  employeeId: georgiewash
                  volunteerType: Employee
                  firstName: George
                  lastName: Washington
                  department: n/a
                  businessUnit: n/a
                  jobTier: n/a
                  location: n/a
                  workCity: Los Angeles
                  workState: CA
                  workCountryCode: US
                  volunteerHours: 5
                  vtoHours: n/a
                  vtoHoursLoggedToHris: n/a
                  volunteerOrganization: Team Rubicon
                  charityId: cl3f8w2d10009pq9s0b4y2m6h
                  ein: "271720480"
                  nteeCode: M20
                  charityState: CA
                  irsDescription: Team Rubicon’s mission is providing relief to those affected by disaster, no matter when or where they strike. By pairing the skills and experiences of military veterans with first responders, medical professionals, and technology solutions, Team Rubicon aims to provide the greatest service and impact possible. Founded in 2010, Team Rubicon has deployed across the United States and around the world to provide immediate relief to those impacted by disasters and humanitarian crises.
                  hoursType: Individual
                  groundswellIssueAreas: Disaster Relief
                  volunteerStatus: Approved
                  matchAmount: n/a
                  matchStatus: "-"
                  eventId: n/a
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/corporation/download-volunteer-events:
    get:
      tags:
        - Reports
      operationId: getVolunteerEventsReport
      summary: Volunteer events
      description: |
        List of all published volunteer events, including shifts, participants and related charities. Also includes event metadata.

        Unlike the other reports, this one returns JSON by default and ignores the `Accept` header. Set `format=csv` to get a CSV file instead.

        In `participants`, `employeeId` is Groundswell's ID for the employee.
      parameters:
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
            default: json
      responses:
        "200":
          description: The volunteer events report.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportRows"
              example:
                - title: My Event
                  timezone: America/Los_Angeles
                  location:
                    street: 880 Apollo St
                    city: El Segundo
                    state: CA
                    zipCode: "90245"
                    countryCode: US
                  shifts:
                    - name: First Shift
                      start: "2025-02-23T17:18:00.000Z"
                      end: "2025-02-23T19:18:00.000Z"
                      participants:
                        - employeeId: cm5gx41ab0003otm6c7vd2k9q
                          firstName: George
                          lastName: Washington
                          email: george.washington@example.com
                          additionalFields:
                            - department: Accounting
                            - location: New York
                          rsvpStatus: ATTENDING
                          attendance: CHECKED_IN
                          hours:
                            - hours: 2
                              approvalStatus: APPROVED
                    - name: Second Shift
                      start: "2025-02-25T17:18:00.000Z"
                      end: "2025-02-25T19:18:00.000Z"
                      participants: []
                  charities:
                    - id: cl3f8w2d10004pq9s6v1x7k2j
                      name: PAWS NY
                      ein: "800233785"
                      nteeCode: D20
                      address:
                        city: New York
                        state: NY
                        country: US
                        zipCode: "10001"
                  pillar: Community
                  metadata:
                    issueAreas:
                      - Animals
                    skills:
                      - category: Academics
                        description: Anthropology
                    tags:
                      - summer
            text/csv:
              schema:
                $ref: "#/components/schemas/CsvFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/employee/scim/Schemas:
    get:
      tags:
        - SCIM
      operationId: getScimSchemas
      summary: Schemas
      description: Returns the SCIM schemas supported by Groundswell, including the `additionalFields` attribute of the User schema.
      responses:
        "200":
          description: The supported schemas.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimListResponse"
              example:
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:ListResponse
                Resources:
                  - schemas:
                      - urn:ietf:params:scim:schemas:core:2.0:Schema
                    id: urn:ietf:params:scim:schemas:core:2.0:User
                    name: User
                    description: User Account
                    attributes:
                      - name: userName
                        type: string
                        multiValued: false
                        description: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED.
                        required: true
                        caseExact: false
                        mutability: readWrite
                        returned: default
                        uniqueness: server
                      - name: name
                        type: complex
                        multiValued: false
                        description: The user's name - broken down into first and last.
                        required: false
                        subAttributes:
                          - name: familyName
                            type: string
                            multiValued: false
                            description: The family name of the User, or last name in most Western languages (e.g. 'Jensen' given the full name 'Ms. Barbara J Jensen, III').
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: givenName
                            type: string
                            multiValued: false
                            description: The given name of the User, or first name in most Western languages (e.g. 'Barbara' given the full name 'Ms. Barbara J Jensen, III').
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                      - name: preferredLanguage
                        type: string
                        multiValued: false
                        description: Indicates the User's preferred written or spoken language. Generally used for selecting a localized user interface; e.g. 'en_US' specifies the language English and country US.
                        required: false
                        caseExact: false
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                      - name: locale
                        type: string
                        multiValued: false
                        description: Used to indicate the User's default location for purposes of localizing items such as currency, date time format, or numerical representations.
                        required: false
                        caseExact: false
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                      - name: timezone
                        type: string
                        multiValued: false
                        description: The User's time zone in the 'Olson' time zone database format, e.g. 'America/Los_Angeles'.
                        required: false
                        caseExact: false
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                      - name: active
                        type: boolean
                        multiValued: false
                        description: A Boolean value indicating the User's administrative status.
                        required: false
                        mutability: readWrite
                        returned: default
                      - name: emails
                        type: complex
                        multiValued: true
                        description: Email addresses for the user. The value SHOULD be canonicalized by the service provider, e.g. 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.
                        required: false
                        subAttributes:
                          - name: value
                            type: string
                            multiValued: false
                            description: Email addresses for the user. The value SHOULD be canonicalized by the service provider, e.g. 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: display
                            type: string
                            multiValued: false
                            description: A human-readable name, primarily used for display purposes. READ-ONLY.
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: type
                            type: string
                            multiValued: false
                            description: A label indicating the attribute's function, e.g. 'work' or 'home'.
                            required: false
                            caseExact: false
                            canonicalValues:
                              - work
                              - home
                              - other
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: primary
                            type: boolean
                            multiValued: false
                            description: A Boolean value indicating the 'primary' or preferred attribute value for this attribute, e.g. the preferred mailing address or primary email address. The primary attribute value 'true' MUST appear no more than once.
                            required: false
                            mutability: readWrite
                            returned: default
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                      - name: additionalFields
                        type: complex
                        multiValued: false
                        description: Additional fields for the user, such as businessUnit, department, etc. Configured in Groundswell.
                        required: false
                        subAttributes:
                          - name: location
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: jobTier
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: businessUnit
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: department
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: workCity
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: workState
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: workCountryCode
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: customField_1
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: customField_2
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: customField_3
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                          - name: customField_4
                            type: string
                            multiValued: false
                            description: ""
                            required: false
                            caseExact: false
                            mutability: readWrite
                            returned: default
                            uniqueness: none
                        mutability: readWrite
                        returned: default
                        uniqueness: none
                    meta:
                      resourceType: Schema
                      location: /v1/employee/scim/Schemas/urn:ietf:params:scim:schemas:core:2.0:User
                startIndex: 1
                itemsPerPage: 20
                totalResults: 1
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
  /v1/employee/scim/ResourceTypes:
    get:
      tags:
        - SCIM
      operationId: getScimResourceTypes
      summary: ResourceTypes
      description: Returns the SCIM resource types supported by Groundswell.
      responses:
        "200":
          description: The supported resource types.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimListResponse"
              example:
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:ListResponse
                Resources:
                  - schemas:
                      - urn:ietf:params:scim:schemas:core:2.0:ResourceType
                    id: User
                    meta:
                      resourceType: ResourceType
                      location: /v1/employee/scim/ResourceTypes/User
                    name: User
                    description: User Account
                    endpoint: /Users
                    schema: urn:ietf:params:scim:schemas:core:2.0:User
                startIndex: 1
                itemsPerPage: 20
                totalResults: 1
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
  /v1/employee/scim/ServiceProviderConfig:
    get:
      tags:
        - SCIM
      operationId: getScimServiceProviderConfig
      summary: ServiceProviderConfig
      description: Returns the SCIM features supported by Groundswell.
      responses:
        "200":
          description: The service provider configuration.
          content:
            application/scim+json:
              schema:
                type: object
              example:
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig
                meta:
                  resourceType: ServiceProviderConfig
                  location: /v1/employee/scim/ServiceProviderConfig
                documentationUri: https://developers.groundswell.io/#tag/scim
                patch:
                  supported: false
                bulk:
                  supported: false
                  maxOperations: 0
                  maxPayloadSize: 0
                filter:
                  supported: false
                  maxResults: 0
                changePassword:
                  supported: false
                sort:
                  supported: false
                etag:
                  supported: false
                authenticationSchemes:
                  - type: oauthbearertoken
                    name: API key
                    description: Use your API key provided by Groundswell, passing it in the Authorization header as a Bearer token
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
  /v1/employee/scim/Users:
    get:
      tags:
        - SCIM
      operationId: listScimUsers
      summary: Retrieve
      description: |
        Gets an employee by their employee ID, using a `userName` filter. Filtering by `externalId` works the same way.

        Returns a list response with the matching User, or an empty list if there is no employee with that ID.
      parameters:
        - name: filter
          in: query
          required: false
          description: SCIM filter. Use `userName eq "<employee ID>"`.
          schema:
            type: string
          example: 'userName eq "jadams"'
      responses:
        "200":
          description: The matching employees.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimListResponse"
              example:
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:ListResponse
                Resources:
                  - schemas:
                      - urn:ietf:params:scim:schemas:core:2.0:User
                    id: cm9vg6yw300054yp6qgapuhh1
                    externalId: jadams
                    meta:
                      resourceType: User
                      created: "2025-04-24T14:18:21.603Z"
                      lastModified: "2025-04-24T14:18:21.603Z"
                      location: /v1/employee/scim/Users/cm9vg6yw300054yp6qgapuhh1
                    userName: jadams
                    name:
                      familyName: Adams
                      givenName: John
                    preferredLanguage: pt_BR
                    active: true
                    emails:
                      - value: john.adams@example.com
                        type: work
                        primary: true
                    additionalFields:
                      location: New York
                      department: Finance
                startIndex: 1
                itemsPerPage: 20
                totalResults: 1
        "400":
          $ref: "#/components/responses/ScimBadRequest"
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
    post:
      tags:
        - SCIM
      operationId: createScimUser
      summary: Create
      description: |
        Creates an employee.

        - `userName` (the employee ID), `name.givenName`, `name.familyName` and an email in `emails` are required.
        - `emails` should include exactly one entry with `primary: true`, which will be set as the employee's email.
        - Set `active: true` to create an active employee. If `active` is left out, the employee is created as terminated.
        - Additional fields go in `additionalFields`, using the additional field name as the key.
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/ScimUser"
            example:
              schemas:
                - urn:ietf:params:scim:schemas:core:2.0:User
              userName: jadams
              name:
                givenName: John
                familyName: Adams
              emails:
                - value: john.adams@example.com
                  primary: true
                  type: work
              active: true
              preferredLanguage: pt_BR
              additionalFields:
                location: New York
                department: Finance
      responses:
        "201":
          description: Request successful, the created employee is returned.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimUser"
              example:
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                id: cm9vg6yw300054yp6qgapuhh1
                externalId: jadams
                meta:
                  resourceType: User
                  created: "2025-04-24T14:18:21.603Z"
                  lastModified: "2025-04-24T14:18:21.603Z"
                  location: /v1/employee/scim/Users/cm9vg6yw300054yp6qgapuhh1
                userName: jadams
                name:
                  familyName: Adams
                  givenName: John
                preferredLanguage: pt_BR
                active: true
                emails:
                  - value: john.adams@example.com
                    type: work
                    primary: true
                additionalFields:
                  location: New York
                  department: Finance
        "400":
          $ref: "#/components/responses/ScimBadRequest"
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
        "409":
          description: Another employee in your company already has this email or employee ID.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimError"
              example:
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:Error
                status: "409"
                scimType: uniqueness
                detail: Another employee in this corporation already has this email or externalId
  /v1/employee/scim/Users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Groundswell's ID for the employee.
        schema:
          type: string
        example: cm9vg6yw300054yp6qgapuhh1
    get:
      tags:
        - SCIM
      operationId: getScimUser
      summary: Get by ID
      description: Gets an employee by Groundswell's ID.
      responses:
        "200":
          description: Request successful, the employee is returned.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimUser"
              example:
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                id: cm9vg6yw300054yp6qgapuhh1
                externalId: jadams
                meta:
                  resourceType: User
                  created: "2025-04-24T14:18:21.603Z"
                  lastModified: "2025-04-24T14:18:21.603Z"
                  location: /v1/employee/scim/Users/cm9vg6yw300054yp6qgapuhh1
                userName: jadams
                name:
                  familyName: Adams
                  givenName: John
                preferredLanguage: pt_BR
                active: true
                emails:
                  - value: john.adams@example.com
                    type: work
                    primary: true
                additionalFields:
                  location: New York
                  department: Finance
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
        "404":
          $ref: "#/components/responses/ScimNotFound"
    put:
      tags:
        - SCIM
      operationId: replaceScimUser
      summary: Update
      description: |
        Updates an employee. Only the attributes you send are changed, but `userName` is always required: send the employee's current employee ID, or a new one to change it.

        Can be used for setting an employee status to active or terminated by setting `active` to `true` or `false`.
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/ScimUser"
            example:
              schemas:
                - urn:ietf:params:scim:schemas:core:2.0:User
              userName: jadams
              preferredLanguage: es
              additionalFields:
                location: Boston
      responses:
        "200":
          description: Request successful, returns the updated employee.
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/ScimUser"
              example:
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                id: cm9vg6yw300054yp6qgapuhh1
                externalId: jadams
                meta:
                  resourceType: User
                  created: "2025-04-24T14:18:21.603Z"
                  lastModified: "2025-04-24T14:18:45.730Z"
                  location: /v1/employee/scim/Users/cm9vg6yw300054yp6qgapuhh1
                userName: jadams
                name:
                  familyName: Adams
                  givenName: John
                preferredLanguage: es
                active: true
                emails:
                  - value: john.adams@example.com
                    type: work
                    primary: true
                additionalFields:
                  location: Boston
                  department: Finance
        "400":
          $ref: "#/components/responses/ScimBadRequest"
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
        "404":
          $ref: "#/components/responses/ScimNotFound"
    delete:
      tags:
        - SCIM
      operationId: deleteScimUser
      summary: Delete
      description: Terminates an employee. Employees are never deleted from Groundswell, so this has the same effect as an update with `active` set to `false`.
      responses:
        "204":
          description: Employee terminated, the body is empty.
        "401":
          $ref: "#/components/responses/ScimUnauthorized"
        "404":
          $ref: "#/components/responses/ScimNotFound"
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your API key provided by Groundswell. To get one, reach out to our customer support team.
  schemas:
    CsvFile:
      type: string
      description: CSV file, sent as an attachment.
    ReportRows:
      type: array
      description: One object per report row.
      items:
        type: object
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    ScimError:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        status:
          type: string
        scimType:
          type: string
        detail:
          type: string
    ScimListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        Resources:
          type: array
          items:
            type: object
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        totalResults:
          type: integer
    ScimUser:
      type: object
      required:
        - userName
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
          readOnly: true
          description: Groundswell's ID for the employee.
        externalId:
          type: string
          readOnly: true
          description: The employee ID. Set it through `userName`.
        meta:
          type: object
          readOnly: true
        userName:
          type: string
          description: The employee ID in your company.
        name:
          type: object
          properties:
            givenName:
              type: string
            familyName:
              type: string
        preferredLanguage:
          type: string
          description: The employee's language. See the list of options in the SCIM introduction.
        active:
          type: boolean
          description: "`true` for an active employee, `false` for a terminated one."
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              primary:
                type: boolean
        additionalFields:
          type: object
          description: Additional field values, keyed by additional field name.
          properties:
            location:
              type: string
            jobTier:
              type: string
            businessUnit:
              type: string
            department:
              type: string
            workCity:
              type: string
            workState:
              type: string
            workCountryCode:
              type: string
            customField_1:
              type: string
            customField_2:
              type: string
            customField_3:
              type: string
            customField_4:
              type: string
  parameters:
    Accept:
      name: Accept
      in: header
      required: false
      description: By default, the API will return the data as an attached CSV file. If you want to receive it as JSON, set this header to `application/json`.
      schema:
        type: string
        enum:
          - application/json
      example: application/json
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: UnauthorizedError
            code: UNAUTHORIZED
    Forbidden:
      description: The admin who owns the API key isn't allowed to download reports.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: Action Forbidden.
            code: FORBIDDEN
    ScimUnauthorized:
      description: The API key is missing or invalid.
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/ScimError"
          example:
            schemas:
              - urn:ietf:params:scim:api:messages:2.0:Error
            status: "401"
            detail: UnauthorizedError
    ScimBadRequest:
      description: The request is invalid, for example a required value is missing.
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/ScimError"
          example:
            schemas:
              - urn:ietf:params:scim:api:messages:2.0:Error
            status: "400"
            scimType: invalidValue
            detail: "Required attribute 'userName' is missing"
    ScimNotFound:
      description: There is no employee with this ID in your company.
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/ScimError"
          example:
            schemas:
              - urn:ietf:params:scim:api:messages:2.0:Error
            status: "404"
            detail: Resource cm9vg6yw300054yp6qgapuhh1 not found
