Invite Patient to Complete Questionnaire

Sample Use Case: Re-invite Patients to Complete ID/Signature

A common scenario is when patients complete the main intake form but fail to complete the ID verification/signature portion. This endpoint allows you to send them directly to complete only that part.

How It Works

• Use the identification questionnaire ID: identification-questionnaire
• If the patient already has an incomplete ID questionnaire, the existing instance is reused
• The patient picks up where they left off—they do NOT need to redo the intake

Example

POST /ias/patients/patient_xyz789/inviteCompleteQuestionnaire
Content-Type: application/json
Authorization: Bearer <affiliate_token>

{
  "questionnaire": "identification-questionnaire",
  "orderId": "order_def456"
}

Using External SMS Services

If you prefer to use your own SMS provider instead of the built-in SMS:

1. Call the endpoint without inviteType or with "email" to avoid triggering internal SMS
2. The response contains the questionnaire instance
3. Use the link pattern with your external SMS service

Alternative: Use the Get Order Link endpoint to get a link for the entire order:

GET /ias/orders/{orderId}/actions/getOrderLink
Authorization: Bearer <affiliate_token>

This returns a shortened link that takes the patient to complete all pending items on their order, including ID verification

Endpoint

URL: /ias/patients/:id/inviteCompleteQuestionnaire
Method: POST
Authentication: Required (Affiliate Token)
Content-Type: application/json

Authentication

Required Roles:

• AFFILIATE_SUPER_ADMIN
• AFFILIATE_ADMIN
• AFFILIATE_AGENT

Request Parameters

URL Parameters

Request Body

Request Examples

Send Email Invitation

POST /ias/patients/patient_xyz789/inviteCompleteQuestionnaire
Content-Type: application/json
Authorization: Bearer <affiliate_token>

{
  "questionnaire": "questionnaire_abc123",
  "inviteType": "email"
}

Send SMS Invitation

POST /ias/patients/patient_xyz789/inviteCompleteQuestionnaire
Content-Type: application/json
Authorization: Bearer <affiliate_token>

{
  "questionnaire": "questionnaire_abc123",
  "expiryWeeks": 2,
  "inviteType": "sms"
}

Attach Questionnaire to Order

POST /ias/patients/patient_xyz789/inviteCompleteQuestionnaire
Content-Type: application/json
Authorization: Bearer <affiliate_token>

{
  "questionnaire": "questionnaire_abc123",
  "orderId": "order_def456",
  "inviteType": "email"
}

Response

Success Response

Status Code: 200 OK

{
  "id": "qi_abc123",
  "patient": "patient_xyz789",
  "questionnaire": {
    "id": "questionnaire_abc123",
    "title": "Health Assessment",
    "description": "Initial health screening questionnaire"
  },
  "valid": false,
  "expiresAt": "2025-12-19T00:00:00.000Z",
  "createdAt": "2024-12-19T10:30:00.000Z"
}

Response Fields

Error Responses

Notes

• Idempotent: Calling multiple times resends the invitation but doesn't create duplicate instances
• Expiration: Default is 52 weeks; customize with expiryWeeks
• White Labeling: Links automatically use your custom domain if configured

Related Endpoints