NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Members

Change a member's account role

Scopemembers:write

Changes a member's account_role between ADMIN and MEMBER.

  • OWNER: not an assignable value here. An account has exactly one owner, and ownership is handed over only through PUT /v1/accounts/{account_id}/owner, which promotes the new owner and steps the current one down in the same operation.
  • Last owner: the account's last OWNER cannot be demoted.
PATCH
/v1/accounts/{account_id}/members/{member_id}

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

account_idstring

Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.

Formatuuid
member_idstring

Membership unique UUID.

Formatuuid

Request Body

account_rolestring

Who administers the account. Independent of access_level, which says how much access someone has to a given company.

OWNER — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with 422 OWNER_ROLE_NOT_ASSIGNABLE. Ownership moves only through PUT /v1/accounts/{account_id}/owner. ADMIN — everything an OWNER can do, except transferring ownership. MEMBER — no account administration. Access to each company is granted individually and reported as access_level; a member only sees the companies granted to them.

Value in"OWNER" | "ADMIN" | "MEMBER"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "account_role": "ADMIN"  }'
{
  "success": true,
  "data": {
    "member_id": "435a4844-006a-4cfc-a644-e8eb2dd2ca43",
    "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
    "email": "user@example.com",
    "account_role": "OWNER",
    "grants": [
      {
        "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
        "access_level": "VIEW",
        "company_name": "string"
      }
    ],
    "permissions": {
      "can_change_role": true,
      "assignable_roles": [
        "OWNER"
      ],
      "can_remove": true,
      "can_transfer_ownership": true,
      "can_edit_grants": true
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "OWNER_ROLE_RESERVED",
    "message": "Only an owner can assign or transfer the owner role."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "MEMBER_NOT_FOUND",
    "message": "No member with that id belongs to this account."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Retrieve a member GET

Returns one member of the account, with the same shape the list returns.

Remove a member from the account DELETE

Removes a member's access to the account. The account's last `OWNER` cannot be removed.