Skip to main content

1Care Invitations API

These endpoints let B2B admins create, list, and resend 1Care invitations for a client.

note

1Care invitations are email-based. The invited user receives a password setup email and can then sign in to the public 1Care experience with that email address.

Invitation emails use a GOFA-hosted password reset page instead of Firebase's default hosted reset form. After the password setup step is completed successfully, the flow signs the invited user into the tenant-specific 1Care experience and replaces any stale session for a different user on that tenant.

Authentication​

Use one of the following:

  • Authorization: Bearer <firebase_id_token>
  • ClientToken: <client_token>

The caller must have admin access for the target client.

POST /api/client/[clientId]/1care-invitations​

Create a new 1Care invitation and send the onboarding email.

Request Body:

Sample Request
{
  "recipientName": "Wayne",
  "email": "wayne@example.com",
  "message": "Welcome to the 1Care program"
}

Response:

  • 201 Created
Sample Response
{
  "success": true,
  "invitation": {
    "invitationId": "abc123",
    "email": "wayne@example.com",
    "recipientName": "Wayne",
    "status": "pending",
    "emailSent": true,
    "authUserUid": "firebase-auth-uid",
    "authUserExisted": false,
    "setupEmailSentAt": "2026-04-02T10:20:30.000Z"
  }
}
  • 400 Bad Request: invalid request data or a pending invitation already exists for the email
  • 401 Unauthorized or 403 Forbidden: caller does not have access
  • 500 Internal Server Error: invitation creation failed
warning

The error field in failure responses is intended for operator visibility and may contain provider error text. Integrations should display it as-is for admins, but should not depend on exact wording for program logic.

GET /api/client/[clientId]/1care-invitations​

List invitations for a client.

Query Parameters:

  • status (optional): pending, accepted, rejected, or expired
  • limit (optional): integer from 1 to 100, default 50
  • offset (optional): integer, default 0

Response:

  • 200 OK
Sample Response
{
  "invitations": [
    {
      "invitationId": "abc123",
      "email": "wayne@example.com",
      "recipientName": "Wayne",
      "status": "pending",
      "createdAt": "2026-04-02T10:20:30.000Z",
      "expiresAt": "2026-05-02T10:20:30.000Z",
      "setupEmailSentAt": "2026-04-02T10:20:30.000Z",
      "lastSetupEmailSentAt": "2026-04-02T10:20:30.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

All timestamp fields in the list response are returned as ISO 8601 strings when present, including createdAt, expiresAt, respondedAt, authUserProvisionedAt, setupEmailSentAt, and lastSetupEmailSentAt.

  • 400 Bad Request: invalid query parameters
  • 401 Unauthorized or 403 Forbidden: caller does not have access
  • 500 Internal Server Error: listing failed

POST /api/client/[clientId]/1care-invitations/[invitationId]/resend​

Resend the onboarding email for an existing pending invitation and extend the invitation expiry window.

Response:

  • 200 OK
Sample Response
{
  "success": true,
  "invitation": {
    "invitationId": "abc123",
    "email": "wayne@example.com",
    "status": "pending",
    "expiresAt": "2026-05-02T10:20:30.000Z",
    "emailSent": true,
    "authUserUid": "firebase-auth-uid",
    "lastSetupEmailSentAt": "2026-04-02T10:20:30.000Z"
  }
}
  • 400 Bad Request: invitation is not in a resendable state
  • 404 Not Found: invitation does not exist
  • 401 Unauthorized or 403 Forbidden: caller does not have access
  • 500 Internal Server Error: resend failed

Invitation States​

  • pending: invitation has been created and is still actionable
  • accepted: invited user has completed the acceptance flow
  • rejected: invited user explicitly rejected the invitation
  • expired: invitation is no longer valid