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
`is_admin`	boolean	Whether the invited user will have admin privileges
`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

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",
      "is_admin": true,
      "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",
  "is_admin": true,
  "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.is_admin`	boolean	body	Yes	Whether the invited user should have admin privileges

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",
      "is_admin": false
    }
  }'

Example Response


{
  "id": 1,
  "email": "newuser@example.com",
  "display_name": "John Smith",
  "is_admin": false,
  "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.

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[].is_admin`	boolean	body	Yes	Whether the invited user should have admin privileges

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",
        "is_admin": false
      },
      {
        "email": "user2@example.com",
        "display_name": "Bob Johnson",
        "is_admin": true
      }
    ]
  }'

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