openapi: 3.0.3
info:
  title: Submittable API
  description: >-
    The Submittable API (v4) provides read-and-write, programmatic access to
    a Submittable account's data. Submittable is a submission management,
    grants, and applications platform. This API exposes submissions and their
    form-field entries, projects and forms, submitters (users), labels, review
    team members and assignments, funds and payment distributions, and message
    attachments. Authentication uses HTTP Basic Authentication, where an account
    access token (found under More > Integrations > API Access) is sent as the
    password portion of the Basic Auth header. The API is throttled at roughly
    10 transactions per second and 10,000 transactions per hour. In v4,
    submission and label identifiers are GUIDs and list endpoints page with
    continuation tokens rather than page numbers.

    This description is modeled from Submittable's public API reference and help
    documentation. Endpoint paths, parameters, and schemas are honestly modeled
    to reflect the documented resource groups; some request/response shapes are
    generalized where the underlying account-gated reference does not publish a
    machine-readable specification. Endpoints are marked endpointsModeled where
    exact shapes were not confirmable without an authenticated account.
  version: '4.0'
  contact:
    name: Submittable
    url: https://www.submittable.com
  x-endpointsModeled: true
servers:
  - url: https://submittable-api.submittable.com/v4
    description: Submittable API v4 (current)
  - url: https://submittable-api.submittable.com/v3
    description: Submittable API v3 (legacy)
security:
  - basicAuth: []
tags:
  - name: Submissions
    description: Applications and entries sent to your projects.
  - name: Entries
    description: Form-field responses captured on submissions.
  - name: Projects
    description: The forms/programs people apply through.
  - name: Users
    description: Submitters - the people who send submissions.
  - name: Teams
    description: Organization team members and reviewers.
  - name: Assignments
    description: Routing of submissions to reviewers.
  - name: Labels
    description: Tags used to categorize submissions.
  - name: Funds
    description: Budgets and grant distributions.
  - name: Payments
    description: Payment records.
  - name: Messaging
    description: Message attachments.
paths:
  /submissions:
    get:
      operationId: listSubmissions
      tags:
        - Submissions
      summary: List submissions
      description: >-
        List submissions in the account. Supports filtering (for example by
        project, status, label, or date range) and pagination via a
        continuation token.
      parameters:
        - name: projectId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter submissions to a single project.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Filter by submission status.
        - name: continuationToken
          in: query
          required: false
          schema:
            type: string
          description: Token returned by a previous page to fetch the next page.
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
          description: Number of items to return per page.
      responses:
        '200':
          description: A paged list of submissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /submissions/{submissionId}:
    parameters:
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The GUID of the submission.
    get:
      operationId: getSubmission
      tags:
        - Submissions
      summary: Get a submission
      description: Retrieve a single submission by its GUID.
      responses:
        '200':
          description: The requested submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSubmission
      tags:
        - Submissions
      summary: Update a submission
      description: >-
        Update mutable fields on a submission, such as its status or labels.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionUpdate'
      responses:
        '200':
          description: The updated submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entries:
    get:
      operationId: listEntries
      tags:
        - Entries
      summary: List form-field entries
      description: >-
        List the form-field entries (answers) captured against submissions. In
        v4 these consolidate the legacy v3 requests/responses endpoints.
      parameters:
        - name: continuationToken
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A paged list of entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /entries/{entryId}:
    parameters:
      - name: entryId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getEntry
      tags:
        - Entries
      summary: Get an entry
      description: Retrieve a single form-field entry.
      responses:
        '200':
          description: The requested entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entries/submissions/{submissionId}:
    parameters:
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getSubmissionEntries
      tags:
        - Entries
      summary: Get entries for a submission
      description: Retrieve the form-field entries captured on a specific submission.
      responses:
        '200':
          description: The entries for the submission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List projects
      description: List the projects (forms/programs) in the account.
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project
      description: Create a new project (form/program).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreate'
      responses:
        '201':
          description: The created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Get a project
      description: Retrieve a single project by GUID.
      responses:
        '200':
          description: The requested project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateProject
      tags:
        - Projects
      summary: Update a project
      description: Modify a project, including duplicating or updating its settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreate'
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /users:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List submitters
      description: >-
        Retrieve submitters - the people who have created accounts and sent
        submissions to your projects.
      parameters:
        - name: continuationToken
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A paged list of submitters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getUser
      tags:
        - Users
      summary: Get a submitter
      description: Retrieve a single submitter's profile.
      responses:
        '200':
          description: The requested submitter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/team:
    get:
      operationId: listTeamMembers
      tags:
        - Teams
      summary: List team members
      description: List the organization's team members (staff and reviewers).
      responses:
        '200':
          description: A list of team members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /submissions/team/assignment:
    post:
      operationId: assignSubmission
      tags:
        - Assignments
      summary: Assign a submission to a reviewer
      description: >-
        Create a review assignment routing a submission to a team member for
        evaluation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignmentCreate'
      responses:
        '200':
          description: The created assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assignment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /labels:
    get:
      operationId: listLabels
      tags:
        - Labels
      summary: List labels
      description: List the labels (tags) defined in the account.
      responses:
        '200':
          description: A list of labels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLabel
      tags:
        - Labels
      summary: Create a label
      description: Create a new label used to categorize submissions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelCreate'
      responses:
        '201':
          description: The created label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funds:
    get:
      operationId: listFunds
      tags:
        - Funds
      summary: List funds
      description: List the funds (budgets) used to award and disburse grants.
      responses:
        '200':
          description: A list of funds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payments:
    get:
      operationId: listPayments
      tags:
        - Payments
      summary: List payments
      description: >-
        Retrieve payment records, filterable by period (for example year and
        month).
      parameters:
        - name: year
          in: query
          required: false
          schema:
            type: integer
        - name: month
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /messaging/{messageId}/files:
    parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getMessageFiles
      tags:
        - Messaging
      summary: Get message attachments
      description: Retrieve the files attached to a message.
      responses:
        '200':
          description: The attached files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Send your account access token as the
        password portion of the Basic Auth header (the username may be left
        blank or set to your account email, per Submittable's documentation).
  responses:
    Unauthorized:
      description: Authentication failed or was not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        Rate limit exceeded. The API allows roughly 10 transactions per second
        and 10,000 per hour.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Paged:
      type: object
      properties:
        continuationToken:
          type: string
          nullable: true
          description: Token to pass on the next request to retrieve the next page.
        totalCount:
          type: integer
          nullable: true
    Submission:
      type: object
      properties:
        submissionId:
          type: string
          format: uuid
        title:
          type: string
        status:
          type: string
        projectId:
          type: string
          format: uuid
        submitterId:
          type: string
          format: uuid
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        submittedAt:
          type: string
          format: date-time
    SubmissionUpdate:
      type: object
      properties:
        status:
          type: string
        labelIds:
          type: array
          items:
            type: string
            format: uuid
    SubmissionList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Submission'
    Entry:
      type: object
      properties:
        entryId:
          type: string
        submissionId:
          type: string
          format: uuid
        fieldLabel:
          type: string
        value:
          type: string
    EntryList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Entry'
    Project:
      type: object
      properties:
        projectId:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
        formId:
          type: string
          format: uuid
    ProjectCreate:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
    ProjectList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Project'
    User:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
    UserList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/User'
    Assignment:
      type: object
      properties:
        assignmentId:
          type: string
          format: uuid
        submissionId:
          type: string
          format: uuid
        assigneeId:
          type: string
          format: uuid
        status:
          type: string
    AssignmentCreate:
      type: object
      required:
        - submissionId
        - assigneeId
      properties:
        submissionId:
          type: string
          format: uuid
        assigneeId:
          type: string
          format: uuid
    Label:
      type: object
      properties:
        labelId:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
    LabelCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        color:
          type: string
    LabelList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Label'
    Fund:
      type: object
      properties:
        fundId:
          type: string
          format: uuid
        name:
          type: string
        balance:
          type: number
        currency:
          type: string
    FundList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Fund'
    Payment:
      type: object
      properties:
        paymentId:
          type: string
          format: uuid
        amount:
          type: number
        currency:
          type: string
        recipientId:
          type: string
          format: uuid
        paidAt:
          type: string
          format: date-time
    PaymentList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
    File:
      type: object
      properties:
        fileId:
          type: string
          format: uuid
        fileName:
          type: string
        url:
          type: string
          format: uri
        contentType:
          type: string
    FileList:
      allOf:
        - $ref: '#/components/schemas/Paged'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/File'