Go to section …

Invitations

The invitations API can be used to invite new users to flows.

List invitations

Lists the open (not yet accepted) invitations of a flow.

GET /flows/:organization/:flow/invitations

URL breakdown

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2
[
  {
    "id": 14,
    "state": "pending",
    "email": "person@example.com",
    "flow": "05654aa3-3b13-4a79-8cea-92ed45bdc9a5",
    "url": "https://api.flowdock.com/flows/acme/my-flow/invitations/14"
  },
  {
    "id": 15,
    "state": "pending",
    "email": "otherperson@example.com",
    "flow": "05654aa3-3b13-4a79-8cea-92ed45bdc9a5",
    "url": "https://api.flowdock.com/flows/acme/my-flow/invitations/15"
  }
]
Name Description
id Invitation resource id.
state State of the invitation. Can be pending or accepted. Invitation can be declined by deleting it.
email Email address of the person who received the invitation.
flow Resource id of the flow that this invitation belongs to.
url Invitation resource url.

Get an invitation

Get a single invitation. Shows accepted invitations as well. Data format and fields are the same as in invitations listing.

GET /flows/:organization/:flow/invitations/:id

URL breakdown

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2
{
  "id": 14,
  "state": "pending",
  "email": "person@example.com",
  "flow": "05654aa3-3b13-4a79-8cea-92ed45bdc9a5",
  "url": "https://api.flowdock.com/flows/acme/my-flow/invitations/14"
}

Create invitation

Can be used to create or resend invitation. To resend an invitation, use the same email address that was originally used.

POST /flows/:organization/:flow/invitations

URL breakdown

Parameters

Name Description
email Required The email address to invite.
message An optional message that is added to the invitation.
{
  "email": "someone@example.com",
  "message": "Please join our team's Flow."
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Flowdock-User: 2
{
  "id": 9,
  "state": "pending",
  "email": "person@example.com",
  "flow": "05654aa3-3b13-4a79-8cea-92ed45bdc9a5",
  "url": "https://api.flowdock.com/flows/acme/my-flow/invitations/9"
}

Import address list

This resource can be used to import a list of email addresses and invite them to the flow. If an email address matches an existing user in the organization, the user will be added to the flow immediately.

POST /flows/:organization/:flow/invitations/import

URL breakdown

Parameters

Name Description
list Required A list of email addresses to invite. The list can be separated by commas or linefeeds, and the email addresses can be in either of the following formats: person@example.com or "Joe Smith" <person@example.com>
message An optional message that is added to the invitations.
{
  "list": "someone@example.com, \"Joe Smith\" <person@example.com>",
  "message": "Please join our team's Flow."
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2
{
  "invitations": [
    {
      "id": 9,
      "state": "pending",
      "email": "person@example.com",
      "flow": "acme:my-flow",
      "url": "https://api.flowdock.com/flows/acme/my-flow/invitations/9"
    }
  ],
  "added_users": [
    {
      "id": 1,
      "nick": "Steve",
      "name": "Steve",
      "email": "tide@nodeta.fi",
      "avatar": "https://d1xgiuhrdvh29i.cloudfront.net/avatars/17e5d2cd009f410f75e9eb39f1b54d1c/",
      "status": null,
      "disabled": false,
      "last_activity": 1351230217794,
      "last_ping": 1351230217800
    }
  ],
  "erroneous_emails": [
    {"test@example.invalid": "Invalid email"}
  ]
}
Name Description
invitations An array of the newly created invitations.
added_users An array of the existing users added to the flow.
erroneous_emails An array of problematic email addresses with detailed error descriptions.

Delete invitation

Deletes a single invitation. Only pending invitations can be deleted. Used to decline or cancel an invitation.

DELETE /flows/:organization/:flow/invitations/:id

URL breakdown

Response

HTTP/1.1 204 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2
{}