Organizations API

Manage your organization, team members, roles, and permissions.

Get Organization

Retrieve information about a specific organization.

GET /organizations/{id}

Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Acme Corporation",
    "plan": "professional",
    "status": "active",
    "settings": {
      "documentRetention": 365,
      "allowPublicSharing": false,
      "timezone": "UTC"
    },
    "limits": {
      "monthlyDocuments": 10000,
      "storageGB": 100,
      "users": 50
    },
    "usage": {
      "documentsThisMonth": 1250,
      "storageUsedGB": 45.2,
      "activeUsers": 12
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

List Organizations

Get all organizations you have access to.

GET /organizations

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (active, inactive)
`limit`	integer	Number of results (max 100)
`offset`	integer	Pagination offset

Response

{
  "success": true,
  "data": {
    "organizations": [
      {
        "id": 123,
        "name": "Acme Corporation",
        "plan": "professional",
        "role": "admin",
        "status": "active",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 1
    }
  }
}

List Users

Get all users in the organization.

GET /organization/users

Query Parameters

Parameter	Type	Description
`role`	string	Filter by role
`status`	string	Filter by status (active, invited, suspended)
`limit`	integer	Number of results (max 100)
`offset`	integer	Pagination offset

Response

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 456,
        "email": "user@company.com",
        "name": "John Doe",
        "status": "active",
        "roles": [
          {
            "id": 1,
            "name": "admin",
            "displayName": "Administrator"
          }
        ],
        "permissions": [
          "documents.read",
          "documents.create",
          "users.manage"
        ],
        "lastActive": "2024-01-15T10:30:00Z",
        "invitedAt": "2024-01-01T00:00:00Z",
        "joinedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 12
    }
  }
}

Invite User

Invite a new user to the organization.

POST /organizations/invite

Request Body

{
  "email": "newuser@company.com",
  "roles": ["processor"],
  "message": "Welcome to our document processing team!",
  "permissions": [
    "documents.read",
    "documents.create"
  ]
}

Response

{
  "success": true,
  "data": {
    "invitationId": "inv_abc123",
    "email": "newuser@company.com",
    "status": "sent",
    "roles": ["processor"],
    "expiresAt": "2024-01-22T10:30:00Z",
    "inviteUrl": "https://app.flint.com/invite/abc123",
    "sentAt": "2024-01-15T10:30:00Z"
  }
}

Remove User

Remove a user from the organization.

DELETE /organization/users/{userId}

Response

{
  "success": true,
  "message": "User removed from organization",
  "data": {
    "userId": 456,
    "removedAt": "2024-01-15T10:30:00Z"
  }
}

List Roles

Get all roles available in the organization.

GET /organization/roles

Response

{
  "success": true,
  "data": {
    "roles": [
      {
        "id": 1,
        "name": "admin",
        "displayName": "Administrator",
        "description": "Full access to all features",
        "permissions": [
          "documents.create",
          "documents.read",
          "documents.update",
          "documents.delete",
          "users.manage",
          "settings.manage"
        ],
        "userCount": 2,
        "isDefault": false,
        "createdAt": "2024-01-01T00:00:00Z"
      },
      {
        "id": 2,
        "name": "processor",
        "displayName": "Document Processor",
        "description": "Can process and manage documents",
        "permissions": [
          "documents.create",
          "documents.read",
          "documents.update"
        ],
        "userCount": 8,
        "isDefault": true,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Create Role

Create a new custom role.

POST /organization/roles

Request Body

{
  "name": "reviewer",
  "displayName": "Document Reviewer",
  "description": "Can review and approve processed documents",
  "permissions": [
    "documents.read",
    "documents.approve",
    "documents.export"
  ]
}

Response

{
  "success": true,
  "data": {
    "id": 3,
    "name": "reviewer",
    "displayName": "Document Reviewer",
    "description": "Can review and approve processed documents",
    "permissions": [
      "documents.read",
      "documents.approve",
      "documents.export"
    ],
    "userCount": 0,
    "isDefault": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Update Role

Modify an existing role.

PUT /organization/roles/{roleId}

Request Body

{
  "displayName": "Senior Document Reviewer",
  "description": "Senior reviewer with additional permissions",
  "permissions": [
    "documents.read",
    "documents.approve",
    "documents.export",
    "templates.read"
  ]
}

Response

{
  "success": true,
  "data": {
    "id": 3,
    "name": "reviewer",
    "displayName": "Senior Document Reviewer",
    "description": "Senior reviewer with additional permissions",
    "permissions": [
      "documents.read",
      "documents.approve",
      "documents.export",
      "templates.read"
    ],
    "updatedAt": "2024-01-15T10:35:00Z"
  }
}

Delete Role

Remove a role from the organization.

DELETE /organization/roles/{roleId}

Response

{
  "success": true,
  "message": "Role deleted successfully",
  "data": {
    "affectedUsers": 3,
    "replacementRole": "processor"
  }
}

Assign Role to User

Grant a role to a user.

POST /organization/users/assign-role

Request Body

{
  "userId": 456,
  "roleId": 2
}

Response

{
  "success": true,
  "data": {
    "userId": 456,
    "roleId": 2,
    "roleName": "processor",
    "assignedAt": "2024-01-15T10:30:00Z"
  }
}

Remove Role from User

Remove a role from a user.

POST /organization/users/remove-role

Request Body

{
  "userId": 456,
  "roleId": 2
}

Response

{
  "success": true,
  "data": {
    "userId": 456,
    "roleId": 2,
    "roleName": "processor",
    "removedAt": "2024-01-15T10:30:00Z"
  }
}

Get Document Permissions

View permissions for a specific document.

GET /document/permissions

Query Parameters

Parameter	Type	Required	Description
`documentId`	string	Yes	ID of the document

Response

{
  "success": true,
  "data": {
    "documentId": "doc_abc123",
    "defaultAccess": "organization",
    "permissions": [
      {
        "userId": 456,
        "email": "user@company.com",
        "name": "John Doe",
        "access": "read",
        "grantedBy": 123,
        "grantedAt": "2024-01-15T10:00:00Z"
      },
      {
        "userId": 789,
        "email": "editor@company.com",
        "name": "Jane Smith",
        "access": "edit",
        "grantedBy": 123,
        "grantedAt": "2024-01-15T10:00:00Z"
      }
    ],
    "inheritedPermissions": [
      {
        "source": "role",
        "roleName": "admin",
        "access": "full",
        "userCount": 2
      }
    ]
  }
}

Set Document Permissions

Grant specific users access to a document.

PUT /document/{documentId}/permissions

Request Body

{
  "permissions": [
    {
      "userId": 456,
      "access": "read"
    },
    {
      "userId": 789,
      "access": "edit"
    }
  ],
  "defaultAccess": "none",
  "inheritRolePermissions": true
}

Response

{
  "success": true,
  "data": {
    "documentId": "doc_abc123",
    "permissionsSet": 2,
    "defaultAccess": "none",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Remove Document Permissions

Remove specific user access to a document.

DELETE /document/{documentId}/permissions

Query Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	ID of the user

Response

{
  "success": true,
  "message": "Document permissions removed",
  "data": {
    "documentId": "doc_abc123",
    "userId": 456,
    "removedAt": "2024-01-15T10:30:00Z"
  }
}

Organization Statistics

Get usage statistics and analytics for the organization.

GET /organizations/{id}/statistics

Query Parameters

Parameter	Type	Description
`period`	string	Time period (7d, 30d, 90d, 1y)
`metrics`	string	Comma-separated metrics to include

Response

{
  "success": true,
  "data": {
    "organizationId": 123,
    "period": "30d",
    "summary": {
      "documentsProcessed": 1250,
      "averageProcessingTime": "2.3s",
      "successRate": 0.96,
      "activeUsers": 12,
      "storageUsed": "45.2 GB"
    },
    "usage": {
      "documentsPerDay": [
        { "date": "2024-01-15", "count": 45 },
        { "date": "2024-01-14", "count": 38 }
      ],
      "topUsers": [
        {
          "userId": 456,
          "name": "John Doe",
          "documentsProcessed": 125
        }
      ],
      "topDocumentTypes": [
        {
          "type": "invoice",
          "count": 650,
          "percentage": 52.0
        },
        {
          "type": "bol",
          "count": 400,
          "percentage": 32.0
        }
      ]
    },
    "performance": {
      "averageAccuracy": 0.94,
      "processingTimes": {
        "p50": "1.2s",
        "p95": "4.8s",
        "p99": "12.1s"
      },
      "errorRates": {
        "overall": 0.04,
        "byDocumentType": {
          "invoice": 0.02,
          "bol": 0.06
        }
      }
    }
  }
}

Available Permissions

Document Permissions

documents.create - Upload and create documents
documents.read - View documents and data
documents.update - Edit document properties
documents.delete - Remove documents
documents.share - Share with external users
documents.export - Download and export data
documents.approve - Approve processed documents

Template Permissions

templates.create - Create new templates
templates.read - View existing templates
templates.update - Modify templates
templates.delete - Remove templates
templates.manage - Full template access

User Management Permissions

users.invite - Invite new users
users.manage - Full user management
users.roles - Assign and modify roles
users.remove - Remove users from organization

Organization Permissions

settings.read - View organization settings
settings.manage - Modify organization settings
billing.read - View billing information
billing.manage - Manage billing and subscriptions
analytics.read - View organization analytics

Integration Permissions

integrations.create - Set up integrations
integrations.manage - Manage integrations
webhooks.create - Create webhooks
webhooks.manage - Manage webhooks

Access Levels

Document Access Levels

none - No access
read - View only
edit - View and modify
full - Complete access including delete

Organization Access Levels

member - Basic organization access
admin - Administrative privileges
owner - Full organization control

Error Codes

Code	Description
`ORGANIZATION_NOT_FOUND`	Organization ID doesn't exist
`USER_NOT_FOUND`	User ID doesn't exist
`ROLE_NOT_FOUND`	Role ID doesn't exist
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions for action
`DUPLICATE_EMAIL`	Email already exists in organization
`INVALID_ROLE_NAME`	Role name is invalid or already exists
`CANNOT_REMOVE_LAST_ADMIN`	Cannot remove the last administrator
`USER_ALREADY_MEMBER`	User is already a member
`INVITATION_EXPIRED`	Invitation has expired
`ROLE_IN_USE`	Cannot delete role that is assigned to users

Organizations API

On this page