Custom Invitation Flow

It may be desirable for an application to provide for a custom flow to invite users into a workspace. Here is how such a flow could be implemented.

First POST an invitation request to the workspace resource:

https://api.zenginehq.com/v1/workspace/10001/invitees

With parameters

{
  "email": "someone@example.com",
  "role": {
  	"id": 3
  },
  "notify": false
}

Where:

Parameter	Description
workspace_id	The id of the workspace
email	The deliverable Email address of the user you intend to invite
role.id	The id of the access role for the workspace
notify	False, suppresses automatic email generation

Would respond with:

{
  "status": 200,
  "code": 2000,
  "developerMessage": "Make a note of this inviteCode if you are not sending email invitations. This is the last & only time you will see it!",
  "totalCount": 1,
  "limit": 20,
  "offset": 0,
  "data": {
    "id": 1,
    "workspace": {
      "id": 10001
    },
    "email": "someone@example.com",
    "role": {
      "id": 3
    },
    "claimedByUser": {
      "id": null,
      "resource": null,
      "resourceId": null,
      "username": null,
      "email": null,
      "displayName": null,
      "created": null,
      "modified": null,
      "profile": {
        "firstName": null,
        "lastName": null,
        "publicName": null,
        "publicUrl": null
      },
      "settings": {
        "avatarUrl": null
      }
    },
    "createdByUser": {
      "id": 11,
      "resource": null,
      "resourceId": null,
      "username": "me@example.com",
      "email": "me@example.com",
      "displayName": "me@example.com",
      "created": "2016-11-10T18:33:41+0000",
      "modified": "2017-07-21T14:29:43+0000",
      "profile": {
        "firstName": null,
        "lastName": null,
        "publicName": null,
        "publicUrl": null
      },
      "settings": {
        "avatarUrl": "https://wh-current-assets.s3.amazonaws.com/filter/img_png_40_40/img/59720fcc-f344-4782-8723-5608ac110006.png?AWSAccessKeyId=AKIAJSLYTZGTFGF2OG4A&Expires=1816528857&Signature=mZ%2BbesP%2BlBoDirw8BwoEskXgAa8%3D"
      }
    },
    "inviteCode": "a83b5331fc6dcd93cd9a051f114095e7",
    "created": "2017-07-27T15:20:54+0000",
    "modified": "2017-07-27T15:20:54+0000"
  }
}

The inviteCode return in the response would be programmatically extracted and stored for completing the flow.

Next, you would generate and send your own custom inviation email to the user. The invitateCode would need to be embedded in the body with a link back to your service that will process the invitation if accepted.

For example embedded in a mime, quoted-printable mail body:

=09=09=09=09=09<br><br><a target=3D"_blank" href=3D"https://service=
s.something.com?inviteCode=a83b5331fc6dcd93cd9a051f114095e7&workspace.id=
=3D10001&email=someone%40example.com" style=3D"color: #fff; text-decorat=
ion: none; font-weight: normal; -webkit-border-radius: 2px; -moz-border-rad=
ius: 2px; border-radius: 2px; display: inline-block; background-color: #29b=
2e6; margin: 0 10px 0 0; padding: 6px 40px;">Accept Invitation to Join Cust=
om Workspace</a>

When you receive the request to accept the invitation in your service, extract the inviteCode. Then POST a members request to the original workspace resource:

https://api.zenginehq.com/v1/workspace/10001/members

With parameters

{
  "inviteCode": "a83b5331fc6dcd93cd9a051f114095e7"
}

Would respond with:

{
  "status": 200,
  "code": 2000
}