{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/finchnode-com/json-schema/finchnode-com-connect-session-schema.json",
  "title": "ConnectSession",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/finchnode-com-api-openapi.yml#/components/schemas/ConnectSession",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "object",
    "status",
    "categories",
    "syncMode",
    "persistentSyncRequested",
    "durationDays",
    "subject",
    "organization",
    "createdAt",
    "expiresAt",
    "completedAt",
    "externalId",
    "returnUrl",
    "environment",
    "sync"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^cs_[a-f0-9]{20}$"
    },
    "object": {
      "type": "string",
      "const": "connect_session"
    },
    "status": {
      "$ref": "#/$defs/ConnectSessionStatus"
    },
    "categories": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Category"
      }
    },
    "syncMode": {
      "type": "string",
      "enum": [
        "one-time",
        "continuous"
      ]
    },
    "persistentSyncRequested": {
      "type": "boolean"
    },
    "durationDays": {
      "type": "integer"
    },
    "subject": {
      "type": [
        "string",
        "null"
      ]
    },
    "organization": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "externalId": {
      "type": [
        "string",
        "null"
      ]
    },
    "returnUrl": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "environment": {
      "$ref": "#/$defs/Environment"
    },
    "sync": {
      "$ref": "#/$defs/SyncState"
    },
    "simulation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "scenario",
        "state"
      ],
      "description": "Present only on a sandbox session simulated with POST /connect/sessions/{sessionId}/simulate. Poll until state is completed or failed; status can read completed earlier.",
      "properties": {
        "scenario": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "starting",
            "user_ready",
            "consented",
            "connected",
            "syncing",
            "completing",
            "completed",
            "failed"
          ]
        },
        "failureCode": {
          "type": "string",
          "description": "Present when state is failed: expired (the Connect session or the simulation ran out of time), subject_error (the synthetic patient could not be created), consent_error (consent could not be collected or the session could not be completed), source_error (the synthetic source could not be connected or imported), or app_suspended (the application was suspended).",
          "enum": [
            "expired",
            "subject_error",
            "consent_error",
            "source_error",
            "app_suspended"
          ]
        }
      }
    }
  },
  "$defs": {
    "Category": {
      "type": "string",
      "enum": [
        "demographics",
        "medications",
        "conditions",
        "labs",
        "vitals",
        "allergies",
        "immunizations",
        "encounters",
        "documents",
        "claims"
      ]
    },
    "ConnectSessionStatus": {
      "type": "string",
      "description": "abandoned and failed are reserved and not currently set.",
      "enum": [
        "pending",
        "collect-consented",
        "system-selected",
        "completed",
        "abandoned",
        "canceled",
        "expired",
        "failed"
      ]
    },
    "Environment": {
      "type": "string",
      "enum": [
        "sandbox",
        "production"
      ]
    },
    "SyncState": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "status",
        "syncId",
        "startedAt",
        "completedAt",
        "grantedCategories",
        "availableCategories",
        "missingCategories",
        "warnings",
        "failure"
      ],
      "properties": {
        "status": {
          "$ref": "#/$defs/SyncStatus"
        },
        "syncId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "startedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "completedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "grantedCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Category"
          }
        },
        "availableCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Category"
          }
        },
        "missingCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Category"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SyncWarning"
          }
        },
        "failure": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "code",
                "message",
                "retryable"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "retryable": {
                  "type": "boolean"
                }
              }
            }
          ]
        }
      }
    },
    "SyncStatus": {
      "type": "string",
      "enum": [
        "not_started",
        "queued",
        "syncing",
        "complete",
        "partial",
        "failed",
        "reauthorization_required"
      ]
    },
    "SyncWarning": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "category": {
          "oneOf": [
            {
              "$ref": "#/$defs/Category"
            },
            {
              "type": "null"
            }
          ]
        },
        "resourceType": {
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      }
    }
  }
}