Operation Details

The Appointment Enhanced Self Check-in API $self-checkin-entry-url enables healthcare organizations to generate secure, time-limited self check-in links for patients. This operation streamlines the patient arrival process by allowing patients to complete check-in procedures remotely or via mobile devices before their scheduled appointments.

Use Cases

This operation is designed to support the following use cases:

• Pre-Appointment Check-in: Generate self check-in links that can be sent to patients via email or SMS prior to their appointment, allowing them to complete demographic verification and other check-in tasks from home.
• Kiosk Integration: Create entry URLs for use with in-office kiosk systems, enabling touchless check-in experiences.
• Mobile App Integration: Provide self check-in links for integration into patient-facing mobile applications.
• Automated Patient Communication: Integrate with automated reminder systems to include check-in links in appointment confirmation and reminder messages.

Security and Expiration

Generated self check-in links include the following security features:

• Time-Limited Validity: Links are valid for up to 7 days from generation
• Usage Limitations: Each link can be used up to 10 times to accommodate multiple attempts if needed
• Demographic Verification: Patients must verify their demographic information after following the link to ensure identity confirmation

Workflow Overview

1. Link Generation: System generates a unique, secure entry URL for a specific appointment
2. Distribution: Link is distributed to the patient via the specified distribution mechanism (email, SMS, or retrieved for custom distribution)
3. Patient Access: Patient clicks the link and is directed to the self check-in interface
4. Demographic Verification: Patient enters and confirms their demographic information
5. Check-in Completion: Upon successful verification, patient completes the check-in process

Generated Narrative: OperationDefinition ah-appointment-self-checkin-entry-url

URL: [base]/Appointment/[id]/$self-checkin-entry-url

Parameters

Parameter Details

This OperationDefinition defines the following parameters:

Input Parameters

• patientId (Required) - The unique identifier for the patient associated with the appointment. This must be a valid patient ID in the athenahealth system.
  • Type: string
  • Cardinality: 1..1
  • Example: a-14601.E-411
• brandId (Required) - The identifier for the brand associated with the appointment. The brand determines the patient-facing experience, including portal branding and messaging preferences.
  • Type: string
  • Cardinality: 1..1
  • Example: a-14601.Brand-1
• departmentId (Required) - The identifier for the department where the appointment is scheduled. This ensures the check-in process is associated with the correct clinical location.
  • Type: string
  • Cardinality: 1..1
  • Example: a-14601.Department-1
• distributionMechanism (Optional) - Specifies how the self check-in link should be distributed to the patient. If provided, the system will automatically send the link via the specified channel.
  • Type: string
  • Cardinality: 0..1
  • Accepted values: email, sms
  • Example: email
• distributionRecipient (Optional) - The contact information for the recipient when using automatic distribution. Required if distributionMechanism is specified.
  • Type: string
  • Cardinality: 0..1
  • Format: Email address or phone number depending on distribution mechanism
  • Example: patient@example.com or +15555551234

Output Parameters

• joinLink (Required) - The generated secure self check-in URL that the patient can use to access the check-in interface.
  • Type: uri
  • Cardinality: 1..1
  • Example: https://selfcheckin.px.athena.io/authorization/14601?entry=OUTOFOFFICE_SMS&brandId=1&joincode=0I5u6iLUAauj3ZTVw1dgNDkh7HV-gDu4oZvaxybx

Request Example

POST /fhir/r4/Appointment/a-14601.appt-324552/$self-checkin-entry-url
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientId",
      "valueString": "a-14601.E-411"
    },
    {
      "name": "brandId",
      "valueString": "a-14601.Brand-1"
    },
    {
      "name": "departmentId",
      "valueString": "a-14601.Department-1"
    },
    {
      "name": "distributionMechanism",
      "valueString": "email"
    },
    {
      "name": "distributionRecipient",
      "valueString": "patient@example.com"
    }
  ]
}

Successful Response Example

HTTP 200 OK

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "joinLink",
      "valueUri": "https://selfcheckin.px.athena.io/authorization/14601?entry=OUTOFOFFICE_SMS&brandId=1&joincode=0I5u6iLUAauj3ZTVw1dgNDkh7HV-gDu4oZvaxybx"
    }
  ]
}

Error Response Examples

HTTP 400 - Bad Request

Returned when the request contains invalid parameters or there is a mismatch in the distribution mechanism configuration.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "DistributionMechanismMisMatchError"
    }
  ]
}

Common causes for 400 errors:

• Invalid appointment ID
• Mismatched distribution mechanism and recipient format
• Invalid patient, brand, or department identifiers
• Distribution mechanism specified without recipient

HTTP 500 - Internal Server Error

Returned when an unexpected server error occurs during link generation.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Internal Server Error"
    }
  ]
}

Implementation Notes

Required Scope: This operation requires the system/Appointment.$self-checkin-entry-url scope for authentication.

Link Validity:

• Generated links remain valid for 7 days from creation
• Links can be used up to 10 times within the validity period
• After expiration or usage limit, a new link must be generated

Distribution Options:

• If distributionMechanism and distributionRecipient are provided, the system will automatically send the link and still return it in the response
• If these parameters are omitted, the link is only returned in the response for manual distribution
• Email distribution requires a valid email address format
• SMS distribution requires a valid phone number format with country code

Patient Verification:

• After following the link, patients must enter and verify their demographic information
• Verification helps ensure security and compliance with identity confirmation requirements
• Failed verification attempts do not count against the 10-usage limit

Best Practices:

• Generate links as close to the appointment time as practical to maintain security
• Include clear instructions when distributing links to patients
• Consider the patient’s preferred communication method when choosing distribution mechanism
• Monitor link usage patterns to identify potential issues with patient adoption