Skip to content
FoanFoanFoan Docs

Members

People in your organisation and their roles.

Invite a user to your organisation

Section titled “Invite a user to your organisation”

POST /organisations/{organisationId}/invite

Creates (or re-opens an expired or cancelled) invitation valid for 7 days and emails the invitee a link. The organisationId must be the key’s own organisation.

Scope: org:write

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Body (application/json)

Field Type Required Description
email string yes Email address to invite.
name string yes Invitee’s name.
role string: OWNER, ADMIN, EDITOR, VIEWER no Role the invitee gets on acceptance.

Example request

Terminal window
curl -X POST "https://api.foan.ai/api/v1/organisations/{organisationId}/invite" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anita@example.com","name":"Anita Rao","role":"VIEWER"}'

Response 201

{
  "success": true,
  "data": {
    "id": "cmf3k2j9x0007abcd1234efgh",
    "organisationId": "cmf3k2j9x0001abcd1234efgh",
    "email": "anita@example.com",
    "name": "Anita Rao",
    "role": "VIEWER",
    "invitedById": "cmf3k2j9x0002abcd1234efgh",
    "status": "PENDING",
    "token": "<64-hex-character invitation token>",
    "expiresAt": "2026-09-27T10:15:30.000Z",
    "createdAt": "2026-09-20T10:15:30.000Z",
    "updatedAt": "2026-09-20T10:15:30.000Z",
    "invitedBy": {
      "id": "cmf3k2j9x0002abcd1234efgh",
      "name": "Priya Sharma",
      "email": "priya@example.com"
    }
  },
  "message": "Invitation sent successfully"
}

Errors

Code When
400 Missing email or name, invalid email, name shorter than 2 characters, the user is already a member, or a pending invitation already exists for this email
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:write scope, or organisationId is not the key’s organisation
429 Rate limited

List invitations

Section titled “List invitations”

GET /organisations/{organisationId}/invitations

Lists every invitation of the organisation (all statuses), newest first. The organisationId must be the key’s own organisation.

Scope: org:read

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/organisations/{organisationId}/invitations" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0007abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "email": "anita@example.com",
      "name": "Anita Rao",
      "role": "VIEWER",
      "invitedById": "cmf3k2j9x0002abcd1234efgh",
      "status": "PENDING",
      "token": "<64-hex-character invitation token>",
      "expiresAt": "2026-09-27T10:15:30.000Z",
      "createdAt": "2026-09-20T10:15:30.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "invitedBy": {
        "id": "cmf3k2j9x0002abcd1234efgh",
        "name": "Priya Sharma",
        "email": "priya@example.com"
      }
    }
  ],
  "message": "Invitations retrieved successfully"
}

Errors

Code When
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:read scope, or organisationId is not the key’s organisation
429 Rate limited

List members

Section titled “List members”

GET /members/organisation/{organisationId}/members

Lists the organisation’s members with their roles and user profiles. The owner is always included (added as a virtual OWNER entry if they have no membership row). The organisationId must be the key’s own organisation and the key’s owner must be a member.

Scope: org:read

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/members/organisation/{organisationId}/members" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0004abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "userId": "cmf3k2j9x0003abcd1234efgh",
      "role": "EDITOR",
      "joinedAt": "2026-02-01T09:00:00.000Z",
      "user": {
        "id": "cmf3k2j9x0003abcd1234efgh",
        "name": "Rahul Verma",
        "email": "rahul@example.com",
        "avatar": null,
        "lastLogin": "2026-09-20T10:15:30.000Z",
        "isActive": true,
        "isEmailVerified": true,
        "emailVerifiedAt": "2026-01-10T08:00:00.000Z",
        "isWhitelisted": false,
        "createdAt": "2026-01-10T07:55:00.000Z",
        "updatedAt": "2026-09-20T10:15:30.000Z",
        "deletedAt": null
      },
      "organisation": {
        "id": "cmf3k2j9x0001abcd1234efgh",
        "name": "Sharma Foods",
        "description": "Order confirmation calls",
        "type": "TEAM",
        "visibility": "PRIVATE",
        "ownerId": "cmf3k2j9x0002abcd1234efgh",
        "isActive": true,
        "createdAt": "2026-01-10T07:55:00.000Z",
        "updatedAt": "2026-09-20T10:15:30.000Z",
        "deletedAt": null,
        "billingCountry": "IN",
        "companyName": "Sharma Foods Pvt Ltd",
        "companyRegistrationNumber": null,
        "addressLine1": "12 MG Road",
        "addressLine2": null,
        "city": "Bengaluru",
        "state": "Karnataka",
        "postalCode": "560001",
        "gstin": "29ABCDE1234F1Z5",
        "mobile": "+919876543210",
        "metaData": {}
      }
    }
  ],
  "message": "Organisation members retrieved successfully"
}

Errors

Code When
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:read scope, organisationId is not the key’s organisation, or the key’s owner is not a member
429 Rate limited

Add a member directly

Section titled “Add a member directly”

POST /members/organisation/{organisationId}/members

Adds an existing Foan user to the organisation by user ID, without an invitation. The key’s owner must be OWNER or ADMIN of the key’s organisation.

Scope: org:write

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Body (application/json)

Field Type Required Description
userId string yes ID of an existing Foan user.
role string: OWNER, ADMIN, EDITOR, VIEWER no

Example request

Terminal window
curl -X POST "https://api.foan.ai/api/v1/members/organisation/{organisationId}/members" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"cmf3k2j9x0003abcd1234efgh","role":"EDITOR"}'

Response 201

{
  "success": true,
  "data": {
    "id": "cmf3k2j9x0004abcd1234efgh",
    "organisationId": "cmf3k2j9x0001abcd1234efgh",
    "userId": "cmf3k2j9x0003abcd1234efgh",
    "role": "EDITOR",
    "joinedAt": "2026-02-01T09:00:00.000Z",
    "user": {
      "id": "cmf3k2j9x0003abcd1234efgh",
      "name": "Rahul Verma",
      "email": "rahul@example.com",
      "avatar": null,
      "lastLogin": "2026-09-20T10:15:30.000Z",
      "isActive": true,
      "isEmailVerified": true,
      "emailVerifiedAt": "2026-01-10T08:00:00.000Z",
      "isWhitelisted": false,
      "createdAt": "2026-01-10T07:55:00.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "deletedAt": null
    },
    "organisation": {
      "id": "cmf3k2j9x0001abcd1234efgh",
      "name": "Sharma Foods",
      "description": "Order confirmation calls",
      "type": "TEAM",
      "visibility": "PRIVATE",
      "ownerId": "cmf3k2j9x0002abcd1234efgh",
      "isActive": true,
      "createdAt": "2026-01-10T07:55:00.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "deletedAt": null,
      "billingCountry": "IN",
      "companyName": "Sharma Foods Pvt Ltd",
      "companyRegistrationNumber": null,
      "addressLine1": "12 MG Road",
      "addressLine2": null,
      "city": "Bengaluru",
      "state": "Karnataka",
      "postalCode": "560001",
      "gstin": "29ABCDE1234F1Z5",
      "mobile": "+919876543210",
      "metaData": {}
    }
  },
  "message": "Member added to organisation successfully"
}

Errors

Code When
400 User is already a member
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:write scope, foreign organisation, or the key’s owner is not OWNER/ADMIN
429 Rate limited
500 Unknown userId or invalid role (not validated, fails in the database)

Change a member’s role

Section titled “Change a member’s role”

PUT /members/organisation/{organisationId}/members/{userId}

Changes the role of an existing member. The organisation owner’s role cannot be changed. The key’s owner must be OWNER or ADMIN of the key’s organisation.

Scope: org:write

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.
userId path string yes User ID of the member to change.

Body (application/json)

Field Type Required Description
role string: OWNER, ADMIN, EDITOR, VIEWER yes

Example request

Terminal window
curl -X PUT "https://api.foan.ai/api/v1/members/organisation/{organisationId}/members/{userId}" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"ADMIN"}'

Response 200

{
  "success": true,
  "data": {
    "id": "cmf3k2j9x0004abcd1234efgh",
    "organisationId": "cmf3k2j9x0001abcd1234efgh",
    "userId": "cmf3k2j9x0003abcd1234efgh",
    "role": "ADMIN",
    "joinedAt": "2026-02-01T09:00:00.000Z",
    "user": {
      "id": "cmf3k2j9x0003abcd1234efgh",
      "name": "Rahul Verma",
      "email": "rahul@example.com",
      "avatar": null,
      "lastLogin": "2026-09-20T10:15:30.000Z",
      "isActive": true,
      "isEmailVerified": true,
      "emailVerifiedAt": "2026-01-10T08:00:00.000Z",
      "isWhitelisted": false,
      "createdAt": "2026-01-10T07:55:00.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "deletedAt": null
    },
    "organisation": {
      "id": "cmf3k2j9x0001abcd1234efgh",
      "name": "Sharma Foods",
      "description": "Order confirmation calls",
      "type": "TEAM",
      "visibility": "PRIVATE",
      "ownerId": "cmf3k2j9x0002abcd1234efgh",
      "isActive": true,
      "createdAt": "2026-01-10T07:55:00.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "deletedAt": null,
      "billingCountry": "IN",
      "companyName": "Sharma Foods Pvt Ltd",
      "companyRegistrationNumber": null,
      "addressLine1": "12 MG Road",
      "addressLine2": null,
      "city": "Bengaluru",
      "state": "Karnataka",
      "postalCode": "560001",
      "gstin": "29ABCDE1234F1Z5",
      "mobile": "+919876543210",
      "metaData": {}
    }
  },
  "message": "Member role updated successfully"
}

Errors

Code When
400 Target is the organisation owner
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:write scope, foreign organisation, or the key’s owner is not OWNER/ADMIN
404 User is not a member of this organisation
429 Rate limited
500 Invalid role value (not validated)

Remove a member

Section titled “Remove a member”

DELETE /members/organisation/{organisationId}/members/{userId}

Removes a member from the organisation. The organisation owner cannot be removed. The key’s owner must be OWNER or ADMIN of the key’s organisation.

Scope: org:write

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.
userId path string yes User ID of the member to remove.

Example request

Terminal window
curl -X DELETE "https://api.foan.ai/api/v1/members/organisation/{organisationId}/members/{userId}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": null,
  "message": "Member removed from organisation successfully"
}

Errors

Code When
400 Target is the organisation owner
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:write scope, foreign organisation, or the key’s owner is not OWNER/ADMIN
404 User is not a member of this organisation
429 Rate limited

List a user’s memberships

Section titled “List a user’s memberships”

GET /members/user/{userId}/memberships

Returns the membership rows of the given user. With an API key the userId must be the key owner’s ID (from GET /api-keys/me) and only the membership in the key’s organisation is returned.

Scope: org:read

Parameters

Name In Type Required Description
userId path string yes User ID of the key’s owner. Any other value returns 403.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/members/user/{userId}/memberships" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0004abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "userId": "cmf3k2j9x0002abcd1234efgh",
      "role": "OWNER",
      "joinedAt": "2026-02-01T09:00:00.000Z",
      "user": {
        "id": "cmf3k2j9x0002abcd1234efgh",
        "name": "Priya Sharma",
        "email": "priya@example.com",
        "avatar": null,
        "lastLogin": "2026-09-20T10:15:30.000Z",
        "isActive": true,
        "isEmailVerified": true,
        "emailVerifiedAt": "2026-01-10T08:00:00.000Z",
        "isWhitelisted": false,
        "createdAt": "2026-01-10T07:55:00.000Z",
        "updatedAt": "2026-09-20T10:15:30.000Z",
        "deletedAt": null
      },
      "organisation": {
        "id": "cmf3k2j9x0001abcd1234efgh",
        "name": "Sharma Foods",
        "description": "Order confirmation calls",
        "type": "TEAM",
        "visibility": "PRIVATE",
        "ownerId": "cmf3k2j9x0002abcd1234efgh",
        "isActive": true,
        "createdAt": "2026-01-10T07:55:00.000Z",
        "updatedAt": "2026-09-20T10:15:30.000Z",
        "deletedAt": null,
        "billingCountry": "IN",
        "companyName": "Sharma Foods Pvt Ltd",
        "companyRegistrationNumber": null,
        "addressLine1": "12 MG Road",
        "addressLine2": null,
        "city": "Bengaluru",
        "state": "Karnataka",
        "postalCode": "560001",
        "gstin": "29ABCDE1234F1Z5",
        "mobile": "+919876543210",
        "metaData": {}
      }
    }
  ],
  "message": "User organisation memberships retrieved successfully"
}

Errors

Code When
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:read scope, or userId is not the key owner
429 Rate limited

Invite a user (admin)

Section titled “Invite a user (admin)”

POST /members/organisation/{organisationId}/invite

Same as POST /organisations/{organisationId}/invite, but requires the key’s owner to be OWNER or ADMIN. Creates or re-opens a 7-day invitation and emails the invitee.

Scope: org:write

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Body (application/json)

Field Type Required Description
email string yes Email address to invite.
name string yes Invitee’s name.
role string: OWNER, ADMIN, EDITOR, VIEWER no Role the invitee gets on acceptance.

Example request

Terminal window
curl -X POST "https://api.foan.ai/api/v1/members/organisation/{organisationId}/invite" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anita@example.com","name":"Anita Rao","role":"VIEWER"}'

Response 201

{
  "success": true,
  "data": {
    "id": "cmf3k2j9x0007abcd1234efgh",
    "organisationId": "cmf3k2j9x0001abcd1234efgh",
    "email": "anita@example.com",
    "name": "Anita Rao",
    "role": "VIEWER",
    "invitedById": "cmf3k2j9x0002abcd1234efgh",
    "status": "PENDING",
    "token": "<64-hex-character invitation token>",
    "expiresAt": "2026-09-27T10:15:30.000Z",
    "createdAt": "2026-09-20T10:15:30.000Z",
    "updatedAt": "2026-09-20T10:15:30.000Z",
    "invitedBy": {
      "id": "cmf3k2j9x0002abcd1234efgh",
      "name": "Priya Sharma",
      "email": "priya@example.com"
    }
  },
  "message": "Invitation sent successfully"
}

Errors

Code When
400 Missing email or name, invalid email, name shorter than 2 characters, already a member, or a pending invitation exists
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:write scope, foreign organisation, or the key’s owner is not OWNER/ADMIN
429 Rate limited

List invitations (admin)

Section titled “List invitations (admin)”

GET /members/organisation/{organisationId}/invitations

Lists every invitation of the organisation, newest first. Requires the key’s owner to be OWNER or ADMIN of the key’s organisation.

Scope: org:read

Parameters

Name In Type Required Description
organisationId path string yes Your organisation ID. Must be the API key’s own organisation.

Example request

Terminal window
curl -X GET "https://api.foan.ai/api/v1/members/organisation/{organisationId}/invitations" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cmf3k2j9x0007abcd1234efgh",
      "organisationId": "cmf3k2j9x0001abcd1234efgh",
      "email": "anita@example.com",
      "name": "Anita Rao",
      "role": "VIEWER",
      "invitedById": "cmf3k2j9x0002abcd1234efgh",
      "status": "PENDING",
      "token": "<64-hex-character invitation token>",
      "expiresAt": "2026-09-27T10:15:30.000Z",
      "createdAt": "2026-09-20T10:15:30.000Z",
      "updatedAt": "2026-09-20T10:15:30.000Z",
      "invitedBy": {
        "id": "cmf3k2j9x0002abcd1234efgh",
        "name": "Priya Sharma",
        "email": "priya@example.com"
      }
    }
  ],
  "message": "Invitations retrieved successfully"
}

Errors

Code When
401 Missing, invalid or revoked API key, or the key’s owner is deactivated or no longer in the organisation
403 Missing org:read scope, foreign organisation, or the key’s owner is not OWNER/ADMIN
429 Rate limited