Summary

The Invitations API is a representation of Invitations to a Team within Huddle.

Operations

Create Invitation(s)

To create Invitations, POST a collection of email addresses, a collection of Team links and a message.

The response returns a collection of Invitations. If they are new members, then accepted will be false - indicating that an email has been sent to invite the person into Huddle. If they are an existing member of a company in Huddle, then accepted will be true - the person will be auto-added into the teams and a member summary for them is returned.

The Invitations link is obtained from a particular Workspace and all Team links must be Teams within that Workspace.

Request

The request will invite each of the supplied email addresses into Huddle and all of the supplied teams. Teams are supplied as links with a rel of parent. All invitations will include the same supplied message. Existing Huddle users will only receive the message if the 'isDefaultMessage' flag is set to false.

In the examples [email protected] has never used Huddle before and [email protected] is a member of a company in Huddle.

POST .../membership/workspaces/123/invitations HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  links: [{
    rel: "parent",
    href: "..."
  }],
  "emails": [ "[email protected]", "[email protected]" ],
  "message": "Hello!",
  "isDefaultMessage": false
}

Response

If successful the method returns a 202 Accepted. One invitation will be returned per email address that was supplied in the request, even if the email addresses are being invited into multiple teams.

HTTP/1.1 202 Accepted

{
  "invitations": [
    {
      "email": "[email protected]",
      "accepted": false
    },
    {
      "email": "[email protected]",
      "accepted": true,
      "member": {
        "links": [
          { "rel": "self", "href": "" },
          { "rel": "delete", "href": "" },
          { "rel": "company", "href": "" },
          { "rel": "user", "href": "" },
          { "rel": "avatar", "href": "" },
          { "rel": "profile", "href": "" },
          { "rel": "edit", "href": "" }
        ],
        "displayName": "Existing User",
        "firstName": "Existing",
        "lastName": "User",
        "emailAddress": "[email protected]",
        "role": "Founder",
        "internal": true,
        "companyManager": false,
        "lastLoginDate": 2013-04-04T23:50:34
    }
  ]
}

Invalid/Non-Allowlisted Emails

Request

POST .../membership/workspaces/123/invitations HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  links: [{
    rel: "parent",
    href: "..."
  }],
  "emails": [ "invalid.email", "[email protected]", "[email protected]", "[email protected]" ],
  "message": "Hello!",
  "isDefaultMessage": true,
}

Response

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+json

{
  "links":
  [
   {
    "rel": "companyManager"
    "href": "..."
   }
  ],
  "emails":
  [
    {
      "value": "invalid.email"
      "reason": "Invalid"
    },
    {
      "value": "[email protected]",
      "reason": "NotInAllowlist"
    },
    {
      "value": "[email protected]",
      "reason": "SelfInvited"
    }
  ]
}

Other Responses

Case	Response
Any of the Teams do not exist	400 Bad Request
All of the teams are not within the workspace, which the invitations link was obtained from	400 Bad Request
Any of the email addresses does not conform to RFC standards	400 Bad Request
Any of the email addresses is not allowlisted	400 Bad Request
Actor invited themselves	400 Bad Request
Message is over 2500 characters	400 Bad Request
Invalid authorization token	401 Unauthorized
Actor is not in team or not a workspace manager or a company manager	403 Forbidden
Workspace, which the invitations link was obtained from, does not exist	404 Not Found
Actor is not in the same company as the workspace	404 Not Found