FlintflintDocs

Organizations

Organizations are hierarchy nodes used for delegated access, merchant grouping, and settings inheritance. A merchant can belong to one organization node, and settings policies attached to an organization constrain every descendant scope below it.

External API keys can access organizations within the authenticated merchant's organization subtree. Root organization creation is reserved for Flint-managed setup; public callers create child organizations by providing a parent_organization_id. Each organization carries direct user memberships with owner, admin, operator, or viewer roles and supports ownership transfer. Deletion is rejected while the organization still has active descendant organizations or is linked to an active merchant; after deletion the organization's status is deleted.

Organization-scoped settings policies are managed through the settings API with scope=organization.

Endpoints

List organizations#

GET/v1/organizationsRequires scope: accounts.organizations.read or accounts.organizations.write

Returns the organizations accessible to the caller, filtered to the authenticated merchant's organization subtree for external API keys.

Query parameters
parent_organization_idstring

Optional parent organization filter.

statusenum

Optional organization status filter.

activedeleted
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

sort_byenum

Sort field.

namecreated_atupdated_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
      "name": "Northeast Region",
      "metadata": {
        "segment": "enterprise"
      },
      "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
      "status": "active",
      "created_at": "2026-03-18T09:15:00Z",
      "updated_at": "2026-03-18T09:15:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create organization#

POST/v1/organizationsIdempotentRequires scope: accounts.organizations.write

Creates a child organization within the caller's accessible organization hierarchy.

Request body
metadatamap of string
namestringrequired
parent_organization_idstring
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Northeast Region",
    "metadata": {
      "segment": "enterprise"
    },
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB"
  }'
JSON
{
  "data": {
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "name": "Northeast Region",
    "metadata": {
      "segment": "enterprise"
    },
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
    "status": "active",
    "created_at": "2026-03-18T09:15:00Z",
    "updated_at": "2026-03-18T09:15:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get organization#

GET/v1/organizations/{organization_id}Requires scope: accounts.organizations.read or accounts.organizations.write

Returns an accessible organization by ID.

Path parameters
organization_idstringrequired

Flint organization ID.

Query parameters
expandarray of enum

Supported expansions: parent_organization. Expansion requires accounts.organizations.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=parent_organization&expand=parent_organization. Comma-separated values, expand[]=parent_organization, and numeric expand[0]=parent_organization are accepted for common client compatibility.

parent_organization
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/organizations/org_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update organization#

PATCH/v1/organizations/{organization_id}IdempotentRequires scope: accounts.organizations.write

Applies a sparse update to an accessible organization.

Path parameters
organization_idstringrequired

Flint organization ID.

Request body
metadatamap of string
namestring
parent_organization_idstring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/organizations/org_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Northeast Retail",
    "metadata": {
      "segment": "retail"
    }
  }'
JSON
{
  "data": {
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "name": "Northeast Region",
    "metadata": {
      "segment": "enterprise"
    },
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
    "status": "active",
    "created_at": "2026-03-18T09:15:00Z",
    "updated_at": "2026-03-18T09:15:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete organization#

DELETE/v1/organizations/{organization_id}IdempotentRequires scope: accounts.organizations.write

Soft-deletes an organization when it has no active descendants or merchant links.

Path parameters
organization_idstringrequired

Flint organization ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/organizations/org_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "name": "Northeast Region",
    "metadata": {
      "segment": "enterprise"
    },
    "parent_organization_id": "org_01JQ4X2R0W0RTM8VJQ8YQ7P9AB",
    "status": "active",
    "created_at": "2026-03-18T09:15:00Z",
    "updated_at": "2026-03-18T09:15:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List organization memberships#

GET/v1/organizations/{organization_id}/membershipsRequires scope: accounts.organizations.read or accounts.organizations.write

Returns the direct memberships for an organization.

Path parameters
organization_idstringrequired

Flint organization ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/organizations/org_123/memberships \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX",
      "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
      "role": "admin",
      "status": "active",
      "created_at": "2026-03-18T10:00:00Z",
      "updated_at": "2026-03-18T10:00:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Grant organization membership#

POST/v1/organizations/{organization_id}/membershipsIdempotentRequires scope: accounts.organizations.write

Adds or updates a direct organization membership for a user.

Path parameters
organization_idstringrequired

Flint organization ID.

Request body
roleenumrequired
owneradminoperatorviewer
user_idstringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/organizations/org_123/memberships \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX",
    "role": "admin"
  }'
JSON
{
  "data": {
    "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX",
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "role": "admin",
    "status": "active",
    "created_at": "2026-03-18T10:00:00Z",
    "updated_at": "2026-03-18T10:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Revoke organization membership#

DELETE/v1/organizations/{organization_id}/memberships/{user_id}IdempotentRequires scope: accounts.organizations.write

Revokes a direct organization membership for a user.

Path parameters
organization_idstringrequired

Flint organization ID.

user_idstringrequired

Flint user ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/organizations/org_123/memberships/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
    "user_id": "usr_01JQ4X9G7C2R9M18D1T9EAV1KX"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Transfer organization ownership#

POST/v1/organizations/{organization_id}/transfer-ownershipIdempotentRequires scope: accounts.organizations.write

Transfers the organization owner role to another user.

Path parameters
organization_idstringrequired

Flint organization ID.

Request body
new_owner_user_idstringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/organizations/org_123/transfer-ownership \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "new_owner_user_id": "usr_01JQ4XB5PSE2K16K5M89KFBXW7"
  }'
JSON
{
  "data": {
    "membership": {
      "user_id": "usr_01JQ4XB5PSE2K16K5M89KFBXW7",
      "organization_id": "org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ",
      "role": "owner",
      "status": "active",
      "created_at": "2026-03-18T11:00:00Z",
      "updated_at": "2026-03-18T11:00:00Z"
    },
    "previous_owner_user_id": "usr_01JQ4WYYQJW1V1CQ8QK2KM3KQW"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc