> For the complete documentation index, see [llms.txt](https://docs.mymedtrics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mymedtrics.com/api-reference/connect-api/learners.md).

# Learners

People enrolled in visible programs, their enrollment records, and enrollment filters.

## List program enrollments.

> Returns cursor-paged learner enrollment rows for one visible program.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"ProgramId":{"name":"programId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the program (prog_ prefix). Backed by programs.id."},"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum number of records to return per page. The server may return fewer rows than requested. Values above the maximum (100) are silently clamped to 100. Values below the minimum (1) are silently clamped to 1. The effective value after clamping is always returned in pagination.limit so callers can detect that they hit the gateway ceiling. Per-client max_page_size overrides are documented as a tenant-configurable lower cap that never raises the public ceiling.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},"EnrollmentStatus":{"name":"enrollment_status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"description":"Filter by enrollment status. Unknown or differently-cased values return HTTP 400 with error.code invalid_status."},"IncludeEnded":{"name":"include_ended","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Include enrollments where end_date is not null. Default true so partners can fully sync history. Pass false for current-only feeds (end_date IS NULL)."},"LegacyIdQuery":{"name":"legacy_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by legacy source ID from etl_id_registry. Useful for bridge lookups."}},"schemas":{"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","description":"Cursor pagination envelope. Exposes only limit and next_cursor. Count fields (approximate_total, total_count_exact, or any equivalent) are intentionally absent and reserved for future Medtrics-API-Date additions once a concrete partner use case justifies a count strategy per route. pagination.limit is the effective page size after server-side clamp, not the value the client requested.","required":["limit","next_cursor"],"properties":{"limit":{"type":"integer","description":"Effective page size after server-side clamping. Compare to your requested limit to detect ceiling enforcement."},"next_cursor":{"type":["string","null"],"description":"Opaque keyset cursor. Pass as the cursor query parameter on the next request. null when no more pages exist."}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}},"responses":{"EnrollmentListResponse":{"description":"Cursor-paged enrollment records.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Enrollment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}}},"paths":{"/connect/programs/{programId}/enrollments":{"get":{"operationId":"listProgramEnrollments","tags":["Learners"],"summary":"List program enrollments.","description":"Returns cursor-paged learner enrollment rows for one visible program.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/ProgramId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/EnrollmentStatus"},{"$ref":"#/components/parameters/IncludeEnded"},{"$ref":"#/components/parameters/LegacyIdQuery"}],"responses":{"200":{"$ref":"#/components/responses/EnrollmentListResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## List learners.

> Returns cursor-paged learners scoped to the authenticated API app tenant.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum number of records to return per page. The server may return fewer rows than requested. Values above the maximum (100) are silently clamped to 100. Values below the minimum (1) are silently clamped to 1. The effective value after clamping is always returned in pagination.limit so callers can detect that they hit the gateway ceiling. Per-client max_page_size overrides are documented as a tenant-configurable lower cap that never raises the public ceiling.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},"ProgramIdQuery":{"name":"program_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by program public ID (prog_ prefix). Returns only records belonging to this program."},"EnrollmentStatus":{"name":"enrollment_status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"description":"Filter by enrollment status. Unknown or differently-cased values return HTTP 400 with error.code invalid_status."},"EmailQuery":{"name":"email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"Filter by email address (case-insensitive exact match). Email is unique, so at most one record is returned."},"EmployeeNumberQuery":{"name":"employee_number","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by employee number (exact match). Employee number is unique, so at most one record is returned."}},"schemas":{"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","description":"Cursor pagination envelope. Exposes only limit and next_cursor. Count fields (approximate_total, total_count_exact, or any equivalent) are intentionally absent and reserved for future Medtrics-API-Date additions once a concrete partner use case justifies a count strategy per route. pagination.limit is the effective page size after server-side clamp, not the value the client requested.","required":["limit","next_cursor"],"properties":{"limit":{"type":"integer","description":"Effective page size after server-side clamping. Compare to your requested limit to detect ceiling enforcement."},"next_cursor":{"type":["string","null"],"description":"Opaque keyset cursor. Pass as the cursor query parameter on the next request. null when no more pages exist."}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}},"responses":{"LearnerListResponse":{"description":"Cursor-paged learner records.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Learner"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}}},"paths":{"/connect/learners":{"get":{"operationId":"listLearners","tags":["Learners"],"summary":"List learners.","description":"Returns cursor-paged learners scoped to the authenticated API app tenant.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/ProgramIdQuery"},{"$ref":"#/components/parameters/EnrollmentStatus"},{"$ref":"#/components/parameters/EmailQuery"},{"$ref":"#/components/parameters/EmployeeNumberQuery"}],"responses":{"200":{"$ref":"#/components/responses/LearnerListResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Create a learner.

> Atomically creates an auth identity, profile, and primary enrollment in one transaction. Requires learners:write scope. A learner is always created enrolled: primary\_affiliation is required, with program\_id, role\_id and start\_date, because a learner is only visible to the API through a program enrollment. Returns 422 when primary\_affiliation, role\_id or start\_date is missing or the role cannot be assigned in that program, and 404 when the program or role is outside the app's tenant or the role is not active in a program that curates its roles.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}},"responses":{"LearnerItemResponse":{"description":"Single learner record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Learner"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"A resource with a conflicting unique field already exists (409). Code: duplicate_resource. details.field names the request field to change, for example email or employee_number on a learner, program_id when the learner is already actively enrolled in that program, or name on a webhook subscription. Key values are never echoed.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request payload is syntactically valid but fails HTTPS validation. Used for createWebhookSubscription when target_url is not a valid HTTPS URL. invalid_webhook_events (HTTP 400) and invalid_webhook_tolerance (HTTP 400) are returned via the BadRequest response, not here.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/learners":{"post":{"operationId":"createLearner","tags":["Learners"],"summary":"Create a learner.","description":"Atomically creates an auth identity, profile, and primary enrollment in one transaction. Requires learners:write scope. A learner is always created enrolled: primary_affiliation is required, with program_id, role_id and start_date, because a learner is only visible to the API through a program enrollment. Returns 422 when primary_affiliation, role_id or start_date is missing or the role cannot be assigned in that program, and 404 when the program or role is outside the app's tenant or the role is not active in a program that curates its roles.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name","email","primary_affiliation"],"properties":{"first_name":{"type":"string","maxLength":255},"last_name":{"type":"string","maxLength":255},"middle_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":"string","nullable":true},"cc_email":{"type":"string","nullable":true},"cell_phone":{"type":"string","nullable":true},"home_phone":{"type":"string","nullable":true},"work_mobile_phone":{"type":"string","nullable":true},"send_invitation":{"type":"boolean","description":"When true, marks the learner as invitation-sent (sets invitation_sent_at)."},"employee_number":{"type":"string","nullable":true},"class_of":{"type":"string","nullable":true},"is_active":{"type":"boolean","default":true},"home_institution":{"type":"string","description":"Public ID of the learner's home clinical site (site_ prefix).","nullable":true},"primary_affiliation":{"type":"object","description":"The learner's primary program enrollment, created in the same transaction.","required":["program_id","role_id","start_date"],"properties":{"program_id":{"type":"string","description":"prog_ public ID"},"role_id":{"type":"string","description":"role_ public ID"},"start_date":{"type":"string","format":"date"}}}}}}}},"responses":{"201":{"$ref":"#/components/responses/LearnerItemResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get a learner.

> Returns one learner when visible through the authenticated API app tenant.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"LearnerId":{"name":"learnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."}},"responses":{"LearnerItemResponse":{"description":"Single learner record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Learner"}}}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/learners/{learnerId}":{"get":{"operationId":"getLearner","tags":["Learners"],"summary":"Get a learner.","description":"Returns one learner when visible through the authenticated API app tenant.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/LearnerId"}],"responses":{"200":{"$ref":"#/components/responses/LearnerItemResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Replace a learner's writable fields.

> Requires all non-nullable writable fields (first\_name, last\_name, email). Optional fields absent from the body are treated as provided (their current values are preserved for this iteration — v1 uses COALESCE semantics for PUT). Requires learners:write scope.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"LearnerId":{"name":"learnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."}},"responses":{"LearnerItemResponse":{"description":"Single learner record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Learner"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"A resource with a conflicting unique field already exists (409). Code: duplicate_resource. details.field names the request field to change, for example email or employee_number on a learner, program_id when the learner is already actively enrolled in that program, or name on a webhook subscription. Key values are never echoed.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request payload is syntactically valid but fails HTTPS validation. Used for createWebhookSubscription when target_url is not a valid HTTPS URL. invalid_webhook_events (HTTP 400) and invalid_webhook_tolerance (HTTP 400) are returned via the BadRequest response, not here.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/learners/{learnerId}":{"put":{"operationId":"putLearner","tags":["Learners"],"summary":"Replace a learner's writable fields.","description":"Requires all non-nullable writable fields (first_name, last_name, email). Optional fields absent from the body are treated as provided (their current values are preserved for this iteration — v1 uses COALESCE semantics for PUT). Requires learners:write scope.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/LearnerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string","maxLength":255},"last_name":{"type":"string","maxLength":255},"middle_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":"string","nullable":true},"cc_email":{"type":"string","nullable":true},"cell_phone":{"type":"string","nullable":true},"home_phone":{"type":"string","nullable":true},"work_mobile_phone":{"type":"string","nullable":true},"employee_number":{"type":"string","nullable":true},"class_of":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"home_site_id":{"type":"string","nullable":true}}}}}},"responses":{"200":{"$ref":"#/components/responses/LearnerItemResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Partially update a learner.

> Applies only the provided fields to the learner profile. Absent fields are left unchanged. Requires learners:write scope. Known read-only fields (id, created\_at, etc.) are silently ignored; genuinely unknown fields are rejected.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"LearnerId":{"name":"learnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."}},"responses":{"LearnerItemResponse":{"description":"Single learner record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Learner"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"A resource with a conflicting unique field already exists (409). Code: duplicate_resource. details.field names the request field to change, for example email or employee_number on a learner, program_id when the learner is already actively enrolled in that program, or name on a webhook subscription. Key values are never echoed.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request payload is syntactically valid but fails HTTPS validation. Used for createWebhookSubscription when target_url is not a valid HTTPS URL. invalid_webhook_events (HTTP 400) and invalid_webhook_tolerance (HTTP 400) are returned via the BadRequest response, not here.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/learners/{learnerId}":{"patch":{"operationId":"patchLearner","tags":["Learners"],"summary":"Partially update a learner.","description":"Applies only the provided fields to the learner profile. Absent fields are left unchanged. Requires learners:write scope. Known read-only fields (id, created_at, etc.) are silently ignored; genuinely unknown fields are rejected.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/LearnerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","maxLength":255},"last_name":{"type":"string","maxLength":255},"middle_name":{"type":"string","nullable":true},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":"string","nullable":true},"cc_email":{"type":"string","nullable":true,"description":"Pass null to clear."},"cell_phone":{"type":"string","nullable":true,"description":"Pass null to clear."},"home_phone":{"type":"string","nullable":true,"description":"Pass null to clear."},"work_mobile_phone":{"type":"string","nullable":true,"description":"Pass null to clear."},"employee_number":{"type":"string","nullable":true},"class_of":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"home_site_id":{"type":"string","nullable":true,"description":"Public ID of the home clinical site (site_ prefix). Pass null to clear."}}}}}},"responses":{"200":{"$ref":"#/components/responses/LearnerItemResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Deactivate a learner.

> Sets the learner's profile to inactive and ends all active tenant-scoped enrollments atomically. Idempotent: deactivating an already-inactive learner returns 200. No DELETE /learners endpoint exists in v1 (legacy lifecycle compliance). Requires learners:write scope.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"LearnerId":{"name":"learnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."}},"responses":{"LearnerItemResponse":{"description":"Single learner record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Learner"}}}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Learner":{"type":"object","description":"A person (backed by profiles.id). One learner may hold zero or more enrollments across visible programs.","required":["id","first_name","last_name","email","status","program_ids","primary_program_id","active_enrollment_count","total_enrollment_count","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":["string","null"]},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","inactive"],"description":"Aggregated status. 'active' if at least one visible enrollment is currently active; otherwise 'inactive'."},"program_ids":{"type":"array","items":{"type":"string"},"description":"Array of distinct prog_ public IDs from this learner's currently active, non-ended, non-deleted enrollments within tenant scope. Returned in stable order (program_id ASC). Empty array is valid when listed with a non-active enrollment_status filter."},"primary_program_id":{"type":["string","null"],"description":"Public ID (prog_ prefix) of the enrollment with is_primary = true and status = 'active', or null if none."},"active_enrollment_count":{"type":"integer"},"total_enrollment_count":{"type":"integer"},"home_site_id":{"type":["string","null"],"description":"Public ID of the learner's home site (site_ prefix), or null when profiles.home_site_id is unset."},"home_site_legacy_id":{"type":["string","null"],"description":"Legacy source_id for the home site from etl_id_registry, or null when no ETL mapping exists."},"role_id":{"type":["string","null"],"description":"Public ID (role_ prefix) of the role on the learner's primary program membership, or null when no primary membership exists."},"role_legacy_id":{"type":["string","null"],"description":"Legacy source_id for that role from etl_id_registry, or null when no ETL mapping exists."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/learners/{learnerId}/deactivate":{"post":{"operationId":"deactivateLearner","tags":["Learners"],"summary":"Deactivate a learner.","description":"Sets the learner's profile to inactive and ends all active tenant-scoped enrollments atomically. Idempotent: deactivating an already-inactive learner returns 200. No DELETE /learners endpoint exists in v1 (legacy lifecycle compliance). Requires learners:write scope.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/LearnerId"}],"responses":{"200":{"$ref":"#/components/responses/LearnerItemResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## List enrollments for a learner.

> Returns cursor-paged enrollment rows for one visible learner within tenant scope. Returns 404 (never 401/403) when the learner is outside tenant scope to avoid existence leaks.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"LearnerId":{"name":"learnerId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the learner (learner_ prefix). Backed by profiles.id."},"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum number of records to return per page. The server may return fewer rows than requested. Values above the maximum (100) are silently clamped to 100. Values below the minimum (1) are silently clamped to 1. The effective value after clamping is always returned in pagination.limit so callers can detect that they hit the gateway ceiling. Per-client max_page_size overrides are documented as a tenant-configurable lower cap that never raises the public ceiling.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},"EnrollmentStatus":{"name":"enrollment_status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"description":"Filter by enrollment status. Unknown or differently-cased values return HTTP 400 with error.code invalid_status."},"IncludeEnded":{"name":"include_ended","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Include enrollments where end_date is not null. Default true so partners can fully sync history. Pass false for current-only feeds (end_date IS NULL)."},"LegacyIdQuery":{"name":"legacy_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by legacy source ID from etl_id_registry. Useful for bridge lookups."}},"schemas":{"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","description":"Cursor pagination envelope. Exposes only limit and next_cursor. Count fields (approximate_total, total_count_exact, or any equivalent) are intentionally absent and reserved for future Medtrics-API-Date additions once a concrete partner use case justifies a count strategy per route. pagination.limit is the effective page size after server-side clamp, not the value the client requested.","required":["limit","next_cursor"],"properties":{"limit":{"type":"integer","description":"Effective page size after server-side clamping. Compare to your requested limit to detect ceiling enforcement."},"next_cursor":{"type":["string","null"],"description":"Opaque keyset cursor. Pass as the cursor query parameter on the next request. null when no more pages exist."}}},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}},"responses":{"EnrollmentListResponse":{"description":"Cursor-paged enrollment records.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Enrollment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}}},"paths":{"/connect/learners/{learnerId}/enrollments":{"get":{"operationId":"listEnrollmentsForLearner","tags":["Learners"],"summary":"List enrollments for a learner.","description":"Returns cursor-paged enrollment rows for one visible learner within tenant scope. Returns 404 (never 401/403) when the learner is outside tenant scope to avoid existence leaks.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/LearnerId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/EnrollmentStatus"},{"$ref":"#/components/parameters/IncludeEnded"},{"$ref":"#/components/parameters/LegacyIdQuery"}],"responses":{"200":{"$ref":"#/components/responses/EnrollmentListResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Create an enrollment.

> Creates a new program\_membership for an existing learner. The learner, program, and role must all be within tenant scope. role\_id must belong to the given program\_id. Requires enrollments:write scope.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}},"responses":{"EnrollmentItemResponse":{"description":"Single enrollment record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Enrollment"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"A resource with a conflicting unique field already exists (409). Code: duplicate_resource. details.field names the request field to change, for example email or employee_number on a learner, program_id when the learner is already actively enrolled in that program, or name on a webhook subscription. Key values are never echoed.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request payload is syntactically valid but fails HTTPS validation. Used for createWebhookSubscription when target_url is not a valid HTTPS URL. invalid_webhook_events (HTTP 400) and invalid_webhook_tolerance (HTTP 400) are returned via the BadRequest response, not here.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/enrollments":{"post":{"operationId":"createEnrollment","tags":["Learners"],"summary":"Create an enrollment.","description":"Creates a new program_membership for an existing learner. The learner, program, and role must all be within tenant scope. role_id must belong to the given program_id. Requires enrollments:write scope.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["learner_id","program_id","role_id","start_date"],"properties":{"learner_id":{"type":"string","description":"learner_ public ID"},"program_id":{"type":"string","description":"prog_ public ID"},"role_id":{"type":"string","description":"role_ public ID"},"start_date":{"type":"string","format":"date"},"is_primary":{"type":"boolean","default":false},"expected_graduation":{"type":"string","format":"date","nullable":true},"status":{"type":"string","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"],"default":"active"}}}}}},"responses":{"201":{"$ref":"#/components/responses/EnrollmentItemResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get an enrollment.

> Returns one enrollment when visible through the authenticated API app tenant. Returns 404 (never 401/403) when outside tenant scope to avoid existence leaks.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"EnrollmentId":{"name":"enrollmentId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."}},"responses":{"EnrollmentItemResponse":{"description":"Single enrollment record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Enrollment"}}}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/enrollments/{enrollmentId}":{"get":{"operationId":"getEnrollment","tags":["Learners"],"summary":"Get an enrollment.","description":"Returns one enrollment when visible through the authenticated API app tenant. Returns 404 (never 401/403) when outside tenant scope to avoid existence leaks.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/EnrollmentId"}],"responses":{"200":{"$ref":"#/components/responses/EnrollmentItemResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Partially update an enrollment.

> Updates only the provided writable enrollment fields. role\_id change targets the enrollment (not the profile) per the data model. Requires enrollments:write scope.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"EnrollmentId":{"name":"enrollmentId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."}},"responses":{"EnrollmentItemResponse":{"description":"Single enrollment record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Enrollment"}}}}}},"BadRequest":{"description":"Invalid request parameters.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request payload is syntactically valid but fails HTTPS validation. Used for createWebhookSubscription when target_url is not a valid HTTPS URL. invalid_webhook_events (HTTP 400) and invalid_webhook_tolerance (HTTP 400) are returned via the BadRequest response, not here.\n","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/enrollments/{enrollmentId}":{"patch":{"operationId":"patchEnrollment","tags":["Learners"],"summary":"Partially update an enrollment.","description":"Updates only the provided writable enrollment fields. role_id change targets the enrollment (not the profile) per the data model. Requires enrollments:write scope.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/EnrollmentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role_id":{"type":"string","description":"role_ public ID","nullable":true},"start_date":{"type":"string","format":"date"},"expected_graduation":{"type":"string","format":"date","nullable":true},"status":{"type":"string","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"is_primary":{"type":"boolean"}}}}}},"responses":{"200":{"$ref":"#/components/responses/EnrollmentItemResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Deactivate an enrollment.

> Sets enrollment status to inactive and end\_date to today. Idempotent: already-inactive enrollment returns 200. Requires enrollments:write scope.

```json
{"openapi":"3.1.0","info":{"title":"Medtrics Connect API","version":"2026-10-27"},"tags":[{"name":"Learners","description":"People enrolled in visible programs, their enrollment records, and enrollment filters."}],"servers":[{"url":"https://sandbox.mymedtrics.com","description":"Client sandbox — shared demo tenant, X-Medtrics-Sandbox-Key or a sandbox API app"},{"url":"https://{client}.mymedtrics.com","description":"Your Medtrics instance","variables":{"client":{"default":"<client-name>","description":"The tenant subdomain Medtrics assigns to your institution"}}}],"security":[{"BearerToken":[]},{"SandboxApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer"},"SandboxApiKey":{"type":"apiKey","in":"header","name":"X-Medtrics-Sandbox-Key"}},"parameters":{"ApiDateHeader":{"name":"Medtrics-API-Date","in":"header","required":true,"description":"API contract date. Use 2026-10-27 for this version. Contract dates select request behavior: rotation creates require explicit placement references from 2026-10-27; earlier accepted dates retain compatibility handling. Unknown dates return HTTP 400 with error.code unsupported_api_date.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"EnrollmentId":{"name":"enrollmentId","in":"path","required":true,"schema":{"type":"string"},"description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."}},"responses":{"EnrollmentItemResponse":{"description":"Single enrollment record.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Enrollment"}}}}}},"Unauthorized":{"description":"Missing or invalid credentials.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Credential lacks tenant visibility or required scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found or outside tenant scope.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Request or API app rate limit exceeded.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error.","headers":{"Medtrics-Request-ID":{"$ref":"#/components/headers/MedtricsRequestId"},"Medtrics-API-Date":{"$ref":"#/components/headers/MedtricsApiDate"},"Medtrics-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"Medtrics-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Medtrics-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"headers":{"MedtricsRequestId":{"description":"Correlates all gateway logs for the request.","schema":{"type":"string"}},"MedtricsApiDate":{"description":"API contract date applied to the request.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Request limit for the current window.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Remaining requests in the current window.","schema":{"type":"string"}},"RateLimitReset":{"description":"Unix seconds when the current rate-limit window resets.","schema":{"type":"string"}}},"schemas":{"Enrollment":{"type":"object","description":"A single program_memberships row. One enrollment per program_memberships.id, decoupled from learner_id.","required":["id","learner_id","program_id","status","is_primary","started_on","created_at","updated_at"],"properties":{"id":{"type":"string","description":"Public ID of the enrollment (enroll_ prefix). Backed by program_memberships.id."},"learner_id":{"type":"string","description":"Public ID of the learner (learner_ prefix). Backed by program_memberships.user_id."},"program_id":{"type":"string","description":"Public ID of the program (prog_ prefix)."},"status":{"$ref":"#/components/schemas/ProgramMembershipStatus"},"is_primary":{"type":"boolean"},"started_on":{"type":"string","format":"date"},"ended_on":{"type":["string","null"],"format":"date"},"expected_graduation":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProgramMembershipStatus":{"type":"string","description":"Status of a learner enrollment (program_memberships.status). Canonical source is the affiliation_status DB enum.","enum":["active","inactive","graduated","transferred","terminated","on_leave","pending"]},"ErrorEnvelope":{"type":"object","required":["error"],"description":"Structured error envelope. error.code is the machine-readable discriminant. Typed detail schemas are provided for codes where structured data aids client remediation. Use the discriminator.mapping to select the correct variant schema; for all other codes see GenericApiError.\n","properties":{"error":{"anyOf":[{"$ref":"#/components/schemas/InvalidStatusError"},{"$ref":"#/components/schemas/InvalidWebhookEventsError"},{"$ref":"#/components/schemas/RateLimitedError"},{"$ref":"#/components/schemas/CursorResourceMismatchError"},{"$ref":"#/components/schemas/InvalidIdError"},{"$ref":"#/components/schemas/UnsupportedApiDateError"},{"$ref":"#/components/schemas/InactiveClientError"},{"$ref":"#/components/schemas/InvalidWebhookUrlError"},{"$ref":"#/components/schemas/GenericApiError"}],"discriminator":{"propertyName":"code","mapping":{"invalid_status":"#/components/schemas/InvalidStatusError","invalid_webhook_events":"#/components/schemas/InvalidWebhookEventsError","rate_limited":"#/components/schemas/RateLimitedError","cursor_resource_mismatch":"#/components/schemas/CursorResourceMismatchError","invalid_id":"#/components/schemas/InvalidIdError","unsupported_api_date":"#/components/schemas/UnsupportedApiDateError","inactive_client":"#/components/schemas/InactiveClientError","invalid_webhook_url":"#/components/schemas/InvalidWebhookUrlError"}}}}},"InvalidStatusError":{"description":"Returned when a status query parameter value is outside the allowed enum. HTTP 400. details.field identifies the parameter; details.allowed lists every accepted value.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_status"},"details":{"type":"object","required":["field","allowed"],"additionalProperties":false,"description":"Structured remediation data for invalid_status.","properties":{"field":{"type":"string","description":"Query parameter name that received the invalid value (e.g. enrollment_status, status).\n"},"allowed":{"type":"array","items":{"type":"string"},"description":"Full list of accepted values for the parameter."}}}}}]},"ApiErrorBase":{"type":"object","required":["code","message","request_id"],"description":"Common fields shared by every Connect API error response.","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error description."},"request_id":{"type":"string","description":"Request correlation ID. Include this value when reporting issues to support alongside the Medtrics-Request-ID response header.\n"}}},"InvalidWebhookEventsError":{"description":"Returned when event_types contains values not in the approved Connect API event list, or when event_types is empty. HTTP 400. details.unsupported_events lists the rejected entries (empty array when event_types was missing or entirely empty).\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_webhook_events"},"details":{"type":"object","required":["unsupported_events"],"additionalProperties":false,"description":"Structured remediation data for invalid_webhook_events.","properties":{"unsupported_events":{"type":"array","items":{"type":"string"},"description":"Event type strings that are not approved Connect API event names. Empty array indicates event_types was missing or contained only invalid entries.\n"}}}}}]},"RateLimitedError":{"description":"Returned when the request or API app rate limit is exceeded. HTTP 429. details.retry_after_seconds indicates the wait duration before retrying.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"rate_limited"},"details":{"type":"object","required":["retry_after_seconds"],"additionalProperties":false,"description":"Structured remediation data for rate_limited.","properties":{"retry_after_seconds":{"type":"integer","description":"Seconds to wait before retrying. Mirrors the Retry-After response header value.\n"}}}}}]},"CursorResourceMismatchError":{"description":"Returned when the cursor was issued for a different resource type than the endpoint being called. HTTP 400. details.expected_resource is the resource this endpoint serves; details.cursor_resource is what the cursor encodes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"cursor_resource_mismatch"},"details":{"type":"object","required":["expected_resource","cursor_resource"],"additionalProperties":false,"description":"Structured remediation data for cursor_resource_mismatch.","properties":{"expected_resource":{"type":"string","description":"Resource type this endpoint serves (e.g. programs, learners)."},"cursor_resource":{"type":"string","description":"Resource type encoded in the submitted cursor."}}}}}]},"InvalidIdError":{"description":"Returned when a path parameter public ID does not match the expected prefix for the resource. HTTP 400. details.field is the parameter name; details.expected_prefix is the required ID prefix.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"invalid_id"},"details":{"type":"object","required":["field","expected_prefix"],"additionalProperties":false,"description":"Structured remediation data for invalid_id.","properties":{"field":{"type":"string","description":"Path or query parameter name that received the invalid ID."},"expected_prefix":{"type":"string","description":"Required ID prefix for this parameter."}}}}}]},"UnsupportedApiDateError":{"description":"Returned when the Medtrics-API-Date header is missing, malformed (not YYYY-MM-DD), or not a supported contract date. HTTP 400. details.supported_dates lists all accepted values. details.reason is one of \"missing\", \"malformed\", or \"not_supported\".\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","required":["details"],"properties":{"code":{"type":"string","const":"unsupported_api_date"},"details":{"type":"object","required":["reason","supported_dates"],"additionalProperties":false,"description":"Structured remediation data for unsupported_api_date.","properties":{"reason":{"type":"string","enum":["missing","malformed","not_supported"],"description":"Specific cause: \"missing\" when the header is absent, \"malformed\" when the value is not YYYY-MM-DD format, \"not_supported\" when the format is valid but the date is not a known contract date.\n"},"supported_dates":{"type":"array","items":{"type":"string"},"description":"All accepted Medtrics-API-Date values."}}}}}]},"InactiveClientError":{"description":"Returned when the authenticated API client is revoked, expired, deleted, or in a non-active status. HTTP 403. No structured details beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"inactive_client"}}}]},"InvalidWebhookUrlError":{"description":"Returned when target_url fails HTTPS validation or is otherwise rejected. HTTP 422. No structured details field beyond the human-readable message.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"code":{"type":"string","const":"invalid_webhook_url"}}}]},"GenericApiError":{"description":"Catch-all error variant for codes that carry no structured remediation data (invalid_cursor, not_found, invalid_credentials, scope_not_allowed, invalid_webhook_tolerance, internal_error, and any future codes not covered by a typed variant in the discriminator.mapping). details is absent or empty for these codes.\n","allOf":[{"$ref":"#/components/schemas/ApiErrorBase"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":true,"description":"Absent or empty for most generic error codes."}}}]}}},"paths":{"/connect/enrollments/{enrollmentId}/deactivate":{"post":{"operationId":"deactivateEnrollment","tags":["Learners"],"summary":"Deactivate an enrollment.","description":"Sets enrollment status to inactive and end_date to today. Idempotent: already-inactive enrollment returns 200. Requires enrollments:write scope.","parameters":[{"$ref":"#/components/parameters/ApiDateHeader"},{"$ref":"#/components/parameters/EnrollmentId"}],"responses":{"200":{"$ref":"#/components/responses/EnrollmentItemResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mymedtrics.com/api-reference/connect-api/learners.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.