Certifyos Form Submissions API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Form Submissions API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: Form Submissions
  description: APIs for managing form submissions
paths:
  /forms/submissions:
    post:
      summary: Create a new form submission
      description: Creates a new form submission. When createPractitioner is true, also creates or links a practitioner (using data.practitionerData) and a portal crosswalk; returns the form submission response with certifyId and providerCreated. Form submission is created first; on failure the request fails without creating a practitioner.
      operationId: createFormSubmission
      tags:
      - Form Submissions
      parameters:
      - description: When true, creates a facility; response includes certifyId and facilityCreated in addition to form submission data.
        required: false
        name: createFacility
        in: query
        schema:
          type: boolean
          default: false
      - description: When true, creates a practitioner from data.practitionerData and a portal crosswalk; response includes certifyId and providerCreated in addition to form submission data.
        required: false
        name: createPractitioner
        in: query
        schema:
          type: boolean
          default: false
      - description: Tenant (organization) identifier
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
          pattern: ^(?!(?i)null$).+
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFormSubmissionRequest'
        required: true
      responses:
        '201':
          description: Form submission created successfully. When createPractitioner is true, the response includes all form submission fields plus certifyId (tenant crosswalk identifier) and providerCreated (true if a new practitioner was created, false if the practitioner already existed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmissionResponseDto'
        '400':
          description: 'Bad request: invalid or missing request body, or when createPractitioner is true: missing data, missing practitionerData, or practitionerData missing npi/externalId.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Unauthorized: valid JWT is required.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'Forbidden: insufficient permissions.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: 'Internal server error: unexpected failure during form submission or practitioner/crosswalk operations.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - jwt: []
  /forms/submissions/{id}:
    get:
      summary: Get a form submission by ID
      description: Retrieves a single form submission by its unique ID. The response includes organizationId (from tenant), flattened data fields, and standard form submission metadata. Requires tenant-id header and valid JWT.
      operationId: getFormSubmission
      tags:
      - Form Submissions
      parameters:
      - description: Unique identifier of the form submission (UUID)
        example: d453006f-30e2-4a01-841d-962579531c25
        required: true
        name: id
        in: path
        schema:
          type: string
      - description: Tenant (organization) identifier
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
          pattern: ^(?!(?i)null$).+
      responses:
        '200':
          description: Form submission found. Returns the form submission with organizationId and flattened data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmissionResponseDto'
        '404':
          description: 'Not found: no form submission exists for the given ID within the tenant.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Unauthorized: valid JWT is required.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'Forbidden: insufficient permissions.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: 'Internal server error: unexpected failure while fetching the form submission.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - jwt: []
  /v2/forms/submissions:
    post:
      summary: Create a multi-tenant form submission (v2)
      description: Creates a canonical form submission and fans out practitioner/facility crosswalk creation to multiple tenants in parallel. Returns per-tenant results with an aggregated status of success, partial_success, or failed. GCS document uploads are dispatched as Cloud Tasks asynchronously.
      operationId: createMultiTenantFormSubmission
      tags:
      - Form Submissions
      parameters:
      - description: Owning tenant (organization) identifier
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
          pattern: ^(?!(?i)null$).+
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMultiTenantFormSubmissionRequest'
        required: true
      responses:
        '201':
          description: Canonical form submission created. Per-tenant results in tenantResults. HTTP 201 is returned even on partial_success or failed fan-out outcomes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiTenantFormSubmissionResponse'
        '400':
          description: 'Bad request: validation failure (empty tenantIds, mutual exclusion, invalid URLs, etc.)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Unauthorized: valid JWT is required.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'Forbidden: insufficient permissions.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: 'Bad gateway: the DAL returned a null, non-object, or id-less canonical submission response.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: 'Service unavailable: the v2 feature is currently disabled via kill switch.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: 'Internal server error: unexpected error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - jwt: []
components:
  schemas:
    MultiTenantFormSubmissionResponse:
      type: object
      description: Response for a multi-tenant form submission
      properties:
        formSubmissionId:
          type: string
          examples:
          - sub_a1b2c3d4
          description: Unique identifier of the canonical form submission record
        status:
          type: string
          examples:
          - partial_success
          description: 'Aggregated status across all tenants: success, partial_success, or failed'
        tenantResults:
          type: array
          items:
            $ref: '#/components/schemas/TenantSubmissionResult'
          description: Per-tenant processing results
        gcsUploadStarted:
          type: boolean
          examples:
          - false
          description: Reserved for GCS document upload dispatch. Always false in this release; will reflect actual Cloud Task dispatch in a follow-up PR.
    ApiError:
      type: object
      description: Standard API error response containing a list of error objects
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: List of error objects describing validation or processing failures
    CreateFormSubmissionRequest:
      type: object
      required:
      - data
      description: Request payload for creating a form submission
      properties:
        data:
          examples:
          - {}
          description: A flexible object for storing any data related to a form submission. This can include details about the form, the submitted data, and metadata about the submission process.
    TenantSubmissionResult:
      type: object
      description: Result of processing a single tenant in a multi-tenant form submission
      properties:
        tenantId:
          type: string
          examples:
          - tenant_blue_cross
          description: The tenant ID that was processed
        status:
          type: string
          examples:
          - success
          description: 'Processing status for this tenant: success or failed'
        certifyId:
          type: string
          examples:
          - certify_pract_001
          description: Tenant crosswalk certify ID, populated when a tenant crosswalk was created. Empty string when only a portal crosswalk was created.
        errorCode:
          type:
          - string
          - 'null'
          examples:
          - DOWNSTREAM_VALIDATION_ERROR
          description: Error code when status is failed
        errorMessage:
          type:
          - string
          - 'null'
          examples:
          - Missing required payer field
          description: Human-readable error detail when status is failed
    TenantOptions:
      type: object
      description: Per-tenant options for multi-tenant form submission fan-out
      properties:
        createPractitioner:
          type: boolean
          description: When true, creates a tenant practitioner crosswalk in addition to the portal crosswalk. Requires practitionerData to be present in the request.
          default: false
        createFacility:
          type: boolean
          description: When true, creates a tenant facility crosswalk in addition to the portal crosswalk. Requires facilityData to be present in the request.
          default: false
    CreateMultiTenantFormSubmissionRequest:
      type: object
      required:
      - data
      - tenantIds
      description: Request payload for creating a multi-tenant form submission
      properties:
        data:
          examples:
          - {}
          description: A flexible object for storing any data related to a form submission. May contain practitionerData or facilityData (but not both) as nested objects, plus submissionPdfUrl, supportingDocuments, and any other form fields.
        tenantIds:
          type: array
          minItems: 1
          examples:
          - - tenant_blue_cross
            - tenant_presbyterian
          items:
            type: string
          description: List of tenant IDs to fan out to. Must contain at least one entry.
        options:
          type: object
          examples:
          - tenant_blue_cross:
              createPractitioner: true
              createFacility: false
          additionalProperties:
            $ref: '#/components/schemas/TenantOptions'
          description: Per-tenant options controlling crosswalk creation. Keys are tenant IDs. Tenants absent from this map default to createPractitioner=false and createFacility=false.
    ErrorObject:
      type: object
      description: Individual error object containing details about a specific validation or processing error
      properties:
        httpStatus:
          type: integer
          format: int32
          examples:
          - 400
          description: HTTP status code for this error
        reason:
          type: string
          examples:
          - VALIDATION_ERROR
          description: Error reason/code
        title:
          type: string
          examples:
          - 'Validation failed for field: eventTypes'
          description: Error title/summary
        detail:
          type: string
          examples:
          - eventTypes is required and cannot be empty or null
          description: Detailed error message
        rejectedValue:
          type: string
          description: The value that was rejected, omitted for sensitive fields such as SSN
    FormSubmissionResponseDto:
      type: object
      description: Form submission response
      properties:
        id:
          type: string
          examples:
          - d453006f-30e2-4a01-841d-962579531c25
          description: The unique identifier for the form submission
        organizationId:
          type: string
          description: The unique identifier for the client organization within Certify
        mappedData:
          examples:
          - personalInformation:
              lastName: Smith
              firstName: Karen
              middleName: Ann
              suffix: Jr.
              npi: 1010000226
              caqhId: 12345678
              dateOfBirth: '1961-04-26'
              highmarkId: '123456789'
              practitionerType: Medical Doctor
              degree: Medical Doctor
              primarySpecialty: Internal Medicine
              primarySpecialtyRole: PCP
              secondarySpecialty: Infectious Disease
              secondarySpecialtyRole: Specialist
              credentialingContactEmailAddress: credentialing@altoonaprimarycare.com
              credentialingContactName: John Doe
            primaryPracticeLocation:
              buildingLocation: Altoona Medical Suites
              groupNpi: 1010000655
              addressLine1: Address Line 1
              addressLine2: Address Line 2
              city: Altoona
              state: PA
              zip: '16601'
              zipExt: '1234'
              county: Blair County
              fips: '42013'
            credentialingAddress:
              sameAsPrimaryPracticeLocation: true
              buildingLocation: Altoona Medical Suites
              addressLine1: Address Line 1
              addressLine2: Address Line 2
              city: Altoona
              state: PA
              zip: '16601'
              zipExt: '1234'
              county: Blair County
              fips: '42013'
              phoneNumber: 555-555-5555
              phoneExtension: '123'
          description: The mapped responses for the form submission. The structure of this object is flexible and can vary based on the form and its fields.
        submissionData:
          examples:
          - {}
          description: The raw responses for the form submission. The structure of this object is flexible and can vary based on the form and its fields.
        submissionPdf:
          examples:
          - {}
          description: The PDF document of the form submission, if available
        submittedBy:
          $ref: '#/components/schemas/FormSubmissionSubmittedByResponse'
          type: object
          description: The flexible data object containing the submitted by information
        form:
          examples:
          - {}
          description: Information about the form associated with the submission
        formVersionId:
          type: string
          examples:
          - e4dea7d7-6023-4c64-b0f1-777dd0266a02
          description: The id of the version of the form used for this submission
        createdAt:
          type: string
          examples:
          - '2025-01-01T12:00:00Z'
          description: The date and time when the form submission was created
        createdBy:
          type: string
          description: The identifier of the user or system that created the submission
        updatedAt:
          type: string
          examples:
          - '2025-01-01T12:00:00Z'
          description: The date and time when the form submission was last updated
    FormSubmissionSubmittedByResponse:
      type: object
      description: Information about who submitted the form
      properties:
        email:
          type: string
          examples:
          - user@example.com
          description: The email of the user who submitted the form
        user:
          examples:
          - {}
          description: The user information of the person who submitted the form
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)