---
updatedAt: 2026-08-31T09:11:42.000Z
agentTools:
  projectIndex: https://doc.fintecture.com/llms.txt
---

# List a user's memberships

Lists the memberships of a user within the accessible organisation subtree, paginated and ordered by creation. Alternative to `GET /v1/users/{user_id}?include=memberships` for users whose accessible memberships exceed the include cap. Requires an OAC token; a target user with no accessible membership returns 403.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API EXPLORER",
    "version": "3.0.0",
    "description": "Public API\n",
    "contact": {
      "name": "Support",
      "email": "noelia.rodriguez@fintecture.com"
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "samples-languages": [
      "curl",
      "javascript",
      "ruby"
    ]
  },
  "servers": [
    {
      "url": "https://api.sandbox.fintecture.com",
      "description": "Sandbox server"
    },
    {
      "url": "https://api.fintecture.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/v1/memberships": {
      "get": {
        "security": [
          {
            "OAuth2Oac": [
              "users:read"
            ]
          }
        ],
        "tags": [
          "memberships"
        ],
        "summary": "List a user's memberships",
        "description": "Lists the memberships of a user within the accessible organisation subtree, paginated and ordered by creation. Alternative to `GET /v1/users/{user_id}?include=memberships` for users whose accessible memberships exceed the include cap. Requires an OAC token; a target user with no accessible membership returns 403.\n",
        "parameters": [
          {
            "in": "query",
            "name": "filter[user_id]",
            "description": "The user whose memberships are listed",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "7b18c2b0-1d2e-4a3b-9c4d-0e1f2a3b4c5d"
            }
          },
          {
            "in": "query",
            "name": "page[number]",
            "description": "The page number of the response, 1-indexed",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "example": 1,
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "page[size]",
            "description": "The number of results returned on a page, 200 at most",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "example": 200,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memberships retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MembershipResourceBase"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": true,
                      "required": [
                        "total",
                        "page",
                        "size"
                      ],
                      "properties": {
                        "total": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Total number of accessible memberships"
                        },
                        "page": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Current page number"
                        },
                        "size": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Number of items per page"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "membershipsPage": {
                    "summary": "First page of a user's memberships",
                    "description": "Each still-pending membership (invitation not yet accepted) carries its onboarding `invitation_link` (OAC only); it is omitted once the invitation is accepted.",
                    "value": {
                      "data": [
                        {
                          "type": "memberships",
                          "id": "5f1f3a3a-7f9b-4ac1-8b9c-0b2a2b4c6d7e",
                          "attributes": {
                            "status": "active",
                            "role": "admin",
                            "company_id": "3c2a9f02-7f7e-4a8f-8c8c-5c7ab6c1b9d2",
                            "notifications": [
                              {
                                "type": "manual_transfer",
                                "pay_by_bank": true,
                                "created_by_me": true,
                                "created_by_others": false,
                                "received_not_by_fintecture": false,
                                "partial_payment": false
                              }
                            ]
                          }
                        },
                        {
                          "type": "memberships",
                          "id": "8a2b4c6d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
                          "attributes": {
                            "status": "waiting",
                            "role": "viewer",
                            "organisation_node_id": "3c2a9f02-7f7e-4a8f-8c8c-5c7ab6c1b9d1",
                            "invitation_link": "https://console.fintecture.com/auth/invitation?invitationToken=eyJhbGciOi..."
                          }
                        }
                      ],
                      "meta": {
                        "total": 20170,
                        "page": 1,
                        "size": 20
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400-BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/401-Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403-Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404-NotFound"
          },
          "406": {
            "$ref": "#/components/responses/406-NotAcceptable"
          },
          "500": {
            "$ref": "#/components/responses/500-InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "400-BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse400"
            }
          }
        },
        "description": "bad request"
      },
      "401-Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse401"
            }
          }
        },
        "description": "unauthorized"
      },
      "403-Forbidden": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse403"
            }
          }
        },
        "description": "forbidden"
      },
      "404-NotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse404"
            }
          }
        },
        "description": "resource not found"
      },
      "406-NotAcceptable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse406"
            }
          }
        },
        "description": "not acceptable"
      },
      "500-InternalServerError": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/APIResponse500"
            }
          }
        },
        "description": "internal server error"
      }
    },
    "schemas": {
      "APIResponse400": {
        "title": "400 API Response",
        "description": "Definition of the standard API reponse when a 400",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status code",
            "type": "integer",
            "example": 400
          },
          "code": {
            "type": "string",
            "enum": [
              "bad_request",
              "provider_error"
            ],
            "example": "bad_request"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse400Error"
            }
          }
        }
      },
      "APIResponse400Error": {
        "title": "API Response 400 Error",
        "description": "API Response 400 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "bad_request",
              "customer_unknown",
              "account_unknown",
              "session_id_invalid_or_expired",
              "invalid_field",
              "mandatory_field_missing",
              "invalid_debited_account"
            ],
            "example": "bad_request"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Bad request"
          },
          "message": {
            "description": "Error message",
            "type": "string",
            "example": "Invalid parameters or malformed syntax."
          }
        }
      },
      "APIResponse401": {
        "title": "401 API Response",
        "description": "Definition of the standard API reponse when a 401",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status code",
            "type": "integer",
            "example": 401
          },
          "code": {
            "type": "string",
            "enum": [
              "unauthorized"
            ],
            "example": "unauthorized"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse401Error"
            }
          }
        }
      },
      "APIResponse401Error": {
        "title": "API Response 401 Error",
        "description": "API Response 401 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "invalid_token",
              "invalid_scopes",
              "invalid_code",
              "invalid_app_id",
              "invalid_app_url"
            ],
            "example": "bad_request"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Invalid token"
          },
          "message": {
            "description": "Error message",
            "type": "string",
            "example": "The token is either invalid or expired."
          }
        }
      },
      "APIResponse403": {
        "title": "403 API Response",
        "description": "Definition of the standard API reponse when a 403",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status code",
            "type": "integer",
            "example": 403
          },
          "code": {
            "type": "string",
            "enum": [
              "forbidden"
            ],
            "example": "forbidden"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse403Error"
            }
          }
        }
      },
      "APIResponse403Error": {
        "title": "API Response 403 Error",
        "description": "API Response 403 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "forbidden"
            ],
            "example": "forbidden"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Forbidden"
          },
          "message": {
            "description": "Error message",
            "type": "string",
            "example": "Access Forbidden."
          }
        }
      },
      "APIResponse404": {
        "title": "404 API Response",
        "description": "Definition of the standard API reponse when a 404",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status code",
            "type": "integer",
            "example": 404
          },
          "code": {
            "type": "string",
            "enum": [
              "not_found"
            ],
            "example": "not_found"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse404Error"
            }
          }
        }
      },
      "APIResponse404Error": {
        "title": "API Response 404 Error",
        "description": "API Response 404 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "not_found"
            ],
            "example": "not_found"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Not found"
          },
          "message": {
            "description": "Error message",
            "type": "string",
            "example": "The requested resource could not be found. The requested resource either does not exist or is temporarily down."
          }
        }
      },
      "APIResponse406": {
        "title": "406 API Response",
        "description": "Definition of the standard API reponse when a 406",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status confirmation",
            "type": "integer",
            "example": 406
          },
          "code": {
            "type": "string",
            "enum": [
              "ERR_NOT_ACCEPTABLE"
            ],
            "example": "ERR_NOT_ACCEPTABLE"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse406Error"
            }
          }
        }
      },
      "APIResponse406Error": {
        "title": "API Response 406 Error",
        "description": "API Response 406 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "SCHEMA_VALIDATION_ERROR"
            ],
            "example": "SCHEMA_VALIDATION_ERROR"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Schema validation error"
          },
          "detail": {
            "description": "Error message",
            "type": "string",
            "example": "must NOT have fewer than 1 characters"
          }
        }
      },
      "APIResponse500": {
        "title": "500 API Response",
        "description": "Definition of the standard API reponse when a 500",
        "type": "object",
        "properties": {
          "status": {
            "format": "int32",
            "description": "HTTP status code",
            "type": "integer",
            "example": 500
          },
          "code": {
            "type": "string",
            "enum": [
              "internal_server_error"
            ],
            "example": "internal_server_error"
          },
          "log_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/IdentifierUuidV4"
              },
              {
                "description": "Log unique identifier"
              }
            ]
          },
          "errors": {
            "description": "Errors returned",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIResponse500Error"
            }
          }
        }
      },
      "APIResponse500Error": {
        "title": "API Response 500 Error",
        "description": "API Response 500 Error description",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "internal_server_error"
            ],
            "example": "internal_server_error"
          },
          "title": {
            "description": "Title message",
            "type": "string",
            "example": "Internal Server Error"
          },
          "message": {
            "description": "Error message",
            "type": "string",
            "example": "An internal error has occurred. If the error persists, please contact our support."
          }
        }
      },
      "IdentifierUuidV4": {
        "title": "UUID V4 identifier",
        "description": "UUID V4 identifier",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
        "type": "string",
        "example": "dc5b0048-2a80-4a22-b2f9-fad7d72f074d"
      },
      "MembershipResourceBase": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "id",
          "attributes"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "memberships"
            ],
            "description": "The type of the resource object, always 'memberships' for this schema"
          },
          "id": {
            "type": "string",
            "description": "The unique identifier (UUID) of the membership object",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "role": {
                "type": "string",
                "description": "User role within the company or organisation node",
                "enum": [
                  "admin",
                  "operator",
                  "developer",
                  "sales",
                  "accountant",
                  "viewer",
                  "limited_accountant"
                ]
              },
              "status": {
                "type": "string",
                "description": "Membership status",
                "enum": [
                  "active",
                  "waiting",
                  "deleted"
                ]
              },
              "notifications": {
                "type": "array",
                "description": "Notification preferences for this membership",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "manual_transfer",
                        "incoming_payment",
                        "payer_email_copy"
                      ]
                    },
                    "pay_by_bank": {
                      "type": "boolean"
                    },
                    "created_by_me": {
                      "type": "boolean"
                    },
                    "created_by_others": {
                      "type": "boolean"
                    },
                    "received_not_by_fintecture": {
                      "type": "boolean"
                    },
                    "partial_payment": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "company_id": {
                "type": "string",
                "nullable": true,
                "description": "UUID of the company this membership belongs to. Mutually exclusive with organisation_node_id.",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
              },
              "organisation_node_id": {
                "type": "string",
                "nullable": true,
                "description": "UUID of the organisation node this membership belongs to. Mutually exclusive with company_id.",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
              },
              "invitation_link": {
                "type": "string",
                "description": "Console onboarding link for this membership. Returned when creating the membership (POST /v1/users with a membership, POST /v1/memberships) and on GET /v1/users?include=memberships and GET /v1/users/{user_id}?include=memberships while the invitation is still pending. Omitted once the invitation is accepted. The raw invitation token is never exposed."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "OAuth2Oac": {
        "type": "oauth2",
        "x-default": "<ACCESS TOKEN>",
        "description": "OAC (Organisation Access Credentials — ⚠️ Beta) access token, sent as `Authorization: Bearer {access_token}`.\n\nObtain it from `POST /oauth/accesstoken` with `grant_type=client_credentials`, authenticating with the OAC `client_id` and `client_secret` as Basic credentials (`Basic base64({client_id}:{client_secret})`). The token is valid for 1 hour. See the [OAC guide](https://doc.fintecture.com/docs/request-an-oac-access-token).\n\nThe token only grants the scopes requested when it was created; each endpoint declares the scopes it requires.\n",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oauth/accesstoken",
            "scopes": {
              "organisations:read": "Read access to organisation nodes",
              "organisations:write": "Write access to organisation nodes",
              "companies:read": "Read access to companies",
              "companies:write": "Write access to companies",
              "users:read": "Read access to users and memberships",
              "users:write": "Write access to users and memberships",
              "applications:read": "Read access to applications",
              "applications:write": "Write access to applications",
              "bank_accounts:read": "Read access to bank accounts",
              "bank_accounts:write": "Write access to bank accounts"
            }
          }
        }
      }
    }
  }
}
```