Invites

The Invites API allows you to manage invitations to your organization, including creating bulk invites.

Invite Properties

Property	Type	Description
`id`	integer	Unique identifier for the invite
`email`	string	Email address of the invited user
`display_name`	string	Display name for the invited user
`roles`	array of strings	The roles granted to the invited user
`organization_id`	integer	ID of the organization the invite belongs to
`organization_name`	string	Name of the organization
`expires_at`	string	ISO 8601 timestamp of when the invite expires
`used_at`	string	ISO 8601 timestamp of when the invite was used (null if not used)
`created_at`	string	ISO 8601 timestamp of when the invite was created
`updated_at`	string	ISO 8601 timestamp of when the invite was last updated

Valid Roles

When creating invites, the following role names may be assigned:

provider
provider_assistant
organization_admin

A caller can only assign roles at or below their own permission level. To retrieve the exact set of roles you are permitted to assign, use the Roles endpoint.

Endpoints

List Organization Invites

Retrieve a paginated list of all active invites for your organization.


GET /api/external/invites

Parameters

Parameter	Type	Location	Required	Description
`page`	integer	query	No	Page number for pagination (default: 1)
`per_page`	integer	query	No	Number of results per page (default: 25)

Example Request


curl -X GET "https://api.kismethealth.com/api/external/invites?page=1&per_page=5" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "organization_invites": [
    {
      "id": 1,
      "email": "newuser@example.com",
      "display_name": "John Smith",
      "roles": ["organization_admin", "provider"],
      "organization_id": 123,
      "organization_name": "Acme Healthcare",
      "expires_at": "2025-08-25T14:00:00Z",
      "used_at": null,
      "created_at": "2025-07-16T14:00:00Z",
      "updated_at": "2025-07-16T14:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 5,
    "total_pages": 2,
    "total_count": 6
  }
}

Get Invite Details

Retrieve detailed information about a specific organization invite.


GET /api/external/invites/{id}

Parameters

Parameter	Type	Location	Required	Description
`id`	integer	path	Yes	ID of the organization invite

Example Request


curl -X GET "https://api.kismethealth.com/api/external/invites/1" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "id": 1,
  "email": "newuser@example.com",
  "display_name": "John Smith",
  "roles": ["organization_admin", "provider"],
  "organization_id": 123,
  "organization_name": "Acme Healthcare",
  "expires_at": "2025-08-25T14:00:00Z",
  "used_at": null,
  "created_at": "2025-07-16T14:00:00Z",
  "updated_at": "2025-07-16T14:00:00Z"
}

Create Organization Invite

Create a new invitation to your organization.


POST /api/external/invites

Parameters

Parameter	Type	Location	Required	Description
`organization_invite`	object	body	Yes	Invite details object
`organization_invite.email`	string	body	Yes	Email address of the person to invite
`organization_invite.display_name`	string	body	Yes	Display name for the invited user
`organization_invite.role_names`	array of strings	body	Yes	The roles to grant the invited user (at least one)

Example Request


curl -X POST "https://api.kismethealth.com/api/external/invites" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_invite": {
      "email": "newuser@example.com",
      "display_name": "John Smith",
      "role_names": ["provider"]
    }
  }'

Example Response


{
  "id": 1,
  "email": "newuser@example.com",
  "display_name": "John Smith",
  "roles": ["provider"],
  "organization_id": 123,
  "organization_name": "Acme Healthcare",
  "expires_at": "2025-08-25T14:00:00Z",
  "used_at": null,
  "created_at": "2025-07-16T14:00:00Z",
  "updated_at": "2025-07-16T14:00:00Z"
}

Error Responses

422 Unprocessable Entity: Returned when trying to invite an email that already has a pending invite or existing account in the organization. Also returns 422 if no roles are provided, or if a requested role is not one the caller is permitted to assign.

Bulk Create Organization Invites

Create multiple invitations to your organization in a single request.


POST /api/external/invites/bulk_create

Parameters

Parameter	Type	Location	Required	Description
`organization_invites`	array	body	Yes	Array of invite objects
`organization_invites[].email`	string	body	Yes	Email address of the person to invite
`organization_invites[].display_name`	string	body	Yes	Display name for the invited user
`organization_invites[].role_names`	array of strings	body	Yes	The roles to grant the invited user (at least one)

Example Request


curl -X POST "https://api.kismethealth.com/api/external/invites/bulk_create" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_invites": [
      {
        "email": "user1@example.com",
        "display_name": "Jane Doe",
        "role_names": ["provider"]
      },
      {
        "email": "user2@example.com",
        "display_name": "Bob Johnson",
        "role_names": ["organization_admin", "provider"]
      }
    ]
  }'

Example Response


Status: 201 Created

Note: This endpoint processes invites asynchronously. The invites will be created in the background via job processing.

Delete Organization Invite

Remove a pending invitation from your organization.


DELETE /api/external/invites/{id}

Parameters

Parameter	Type	Location	Required	Description
`id`	integer	path	Yes	ID of the organization invite

Example Request


curl -X DELETE "https://api.kismethealth.com/api/external/invites/1" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


Status: 204 No Content