---
updatedAt: 2026-05-27T10:18:53.000Z
agentTools:
  projectIndex: https://gethapn.readme.io/llms.txt
---

# Creates a new user invitation.

Creates a new user invitation and sends an email to the user with the instructions to create a new account.

The `imeis` parameter allows specifying the devices that the user is allowed to access. 
If this list is empty, user will have full access to the account's devices.

If boundary access is granted, user will have access to all boundaries in the account.
If no boundary access is specified, it defaults to true.

If accessDate is not specified, user will have access to the account starting in the current date.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "description": "The Hapn API is an HTTP interface for managing devices, accounts, and cloud data.",
    "version": "1.0.0",
    "title": "Hapn API",
    "termsOfService": "https://gethapn.com/terms",
    "contact": {
      "name": "Dev",
      "email": "developer@gethapn.com",
      "url": "http://gethapn.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.iotgps.io/v1",
      "description": "Prod"
    },
    {
      "url": "https://api-dev.iotgps.io/v1",
      "description": "Dev"
    }
  ],
  "paths": {
    "/users/invite": {
      "post": {
        "summary": "Creates a new user invitation.",
        "tags": [
          "Users"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvitationBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Create user invitation result",
            "content": {
              "application/json": {
                "schema": {
                  "description": "",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string",
                      "minLength": 1
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "invitationId": {
                          "type": "string",
                          "description": "The invitation identifier."
                        }
                      }
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                },
                "examples": {
                  "example-1": {
                    "value": {
                      "success": true,
                      "message": "ok",
                      "result": {
                        "invitationId": "a6ab0bfd-d4db-4ca6-99f6-0c25f348387b"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        },
        "operationId": "create-user-invitation",
        "description": "Creates a new user invitation and sends an email to the user with the instructions to create a new account.\n\nThe `imeis` parameter allows specifying the devices that the user is allowed to access. \nIf this list is empty, user will have full access to the account's devices.\n\nIf boundary access is granted, user will have access to all boundaries in the account.\nIf no boundary access is specified, it defaults to true.\n\nIf accessDate is not specified, user will have access to the account starting in the current date.\n"
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "message"
        ],
        "x-examples": {
          "example-1": {
            "value": {
              "success": false,
              "message": "Unauthorized"
            }
          }
        }
      },
      "CreateInvitationBody": {
        "description": "Create invitation definition",
        "type": "object",
        "x-examples": {
          "example-1": {
            "email": "user@webmail.com",
            "imeis": [
              "868239050345326",
              "868239050345327"
            ],
            "boundaryAccess": true,
            "accessDate": "2022-12-26T12:28:27.000Z"
          }
        },
        "title": "Create invitation body",
        "properties": {
          "email": {
            "description": "The email of the user that is being invited",
            "type": "string"
          },
          "imeis": {
            "description": "List of device IMEIs that the user is allowed to access. If the list is empty, user will have full access to the account's devices",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "boundaryAccess": {
            "description": "Determines if the user will have access to boundaries",
            "type": "boolean",
            "default": true
          },
          "accessDate": {
            "description": "Date from which the user will have access to the devices data",
            "type": "string"
          }
        },
        "required": [
          "email"
        ]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "example-1": {
                "value": {
                  "success": false,
                  "message": "Unauthorized"
                }
              }
            }
          }
        }
      },
      "Error": {
        "description": "Server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "example-1": {
                "value": {
                  "success": false,
                  "message": "Error"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.usehapn.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Users",
      "description": "User's account"
    }
  ],
  "security": [
    {
      "OAuth2": []
    }
  ]
}
```