Skip to content
FoanFoanFoan Docs

Organisation

Your organisation and its pending invitations.

List your organisations

Section titled “List your organisations”

GET /organisations

Returns the organisations the key’s owner belongs to, filtered to the key’s own organisation, so an API key always gets a one-element list (or an empty one).

Scope: org:read

Example request

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

Response 200

{
  "success": true,
  "data": [
    {
      "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": {},
      "owner": {
        "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
      },
      "members": [
        {
          "id": "cmf3k2j9x0011abcd1234efgh",
          "organisationId": "cmf3k2j9x0001abcd1234efgh",
          "userId": "cmf3k2j9x0002abcd1234efgh",
          "role": "OWNER",
          "joinedAt": "2026-01-10T07:55: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
          }
        },
        {
          "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
          }
        }
      ]
    }
  ],
  "message": "Organisations 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 Key lacks the required scope org:read
429 Rate limited

Get your organisation

Section titled “Get your organisation”

GET /organisations/{id}

Returns one organisation with its owner and members. The id must be the key’s own organisation.

Scope: org:read

Parameters

Name In Type Required Description
id 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/{id}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "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": {},
    "owner": {
      "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
    },
    "members": [
      {
        "id": "cmf3k2j9x0011abcd1234efgh",
        "organisationId": "cmf3k2j9x0001abcd1234efgh",
        "userId": "cmf3k2j9x0002abcd1234efgh",
        "role": "OWNER",
        "joinedAt": "2026-01-10T07:55: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
        }
      },
      {
        "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
        }
      }
    ]
  },
  "message": "Organisation 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 id is not the key’s organisation
404 Organisation not found (or deleted)
429 Rate limited

Update your organisation

Section titled “Update your organisation”

PUT /organisations/{id}

Updates the organisation’s profile fields. Only name, description, type and visibility are written; any other field (owner, metaData, billing fields) is silently ignored. The id must be the key’s own organisation.

Scope: org:write

Parameters

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

Body (application/json)

Field Type Required Description
name string no New organisation name.
description string no
type string: PERSONAL, TEAM no
visibility string: PRIVATE, PUBLIC no

Example request

Terminal window
curl -X PUT "https://api.foan.ai/api/v1/organisations/{id}" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sharma Foods","description":"Order confirmation and feedback calls"}'

Response 200

{
  "success": true,
  "data": {
    "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": {},
    "owner": {
      "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
    },
    "members": [
      {
        "id": "cmf3k2j9x0011abcd1234efgh",
        "organisationId": "cmf3k2j9x0001abcd1234efgh",
        "userId": "cmf3k2j9x0002abcd1234efgh",
        "role": "OWNER",
        "joinedAt": "2026-01-10T07:55: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
        }
      },
      {
        "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
        }
      }
    ]
  },
  "message": "Organisation updated 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:write scope, or id is not the key’s organisation
429 Rate limited
500 An invalid type or visibility value is passed straight to the database and fails as a server error

List organisations for a user

Section titled “List organisations for a user”

GET /organisations/user/{userId}

Returns the organisations of the given user. With an API key the userId must be the key owner’s user ID (get it from GET /api-keys/me) and the result is filtered to the key’s organisation.

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/organisations/user/{userId}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "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": {},
      "owner": {
        "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
      },
      "members": [
        {
          "id": "cmf3k2j9x0011abcd1234efgh",
          "organisationId": "cmf3k2j9x0001abcd1234efgh",
          "userId": "cmf3k2j9x0002abcd1234efgh",
          "role": "OWNER",
          "joinedAt": "2026-01-10T07:55: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
          }
        },
        {
          "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
          }
        }
      ]
    }
  ],
  "message": "User organisations 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 (body is {success:false, error:“Forbidden”})
429 Rate limited