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, supports ownership transfer, and is soft-deleted only when it has no active descendants or merchant links.

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

Endpoints

List organizations#

GET/v1/organizations

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
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/organizationsIdempotent

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
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}

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
Bash
curl https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ \
  -H "Authorization: Bearer YOUR_API_KEY"

Update organization#

PATCH/v1/organizations/{organization_id}Idempotent

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
Bash
curl -X PATCH https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ \
  -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}Idempotent

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
Bash
curl -X DELETE https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ \
  -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}/memberships

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
Bash
curl https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ/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}/membershipsIdempotent

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
Bash
curl -X POST https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ/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}Idempotent

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
Bash
curl -X DELETE https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ/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-ownershipIdempotent

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
Bash
curl -X POST https://api.withflintpay.com/v1/organizations/org_01JQ4X6Q1G6NMBM4Q0E2W9X6YZ/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