Skip to content
Ele API

Organizations and roles

Each of your clients is an organization on Ele. A user can belong to many organizations, with one role in each. Your staff members are users who belong to the client organizations they look after.

Choosing the organization

Section titled “Choosing the organization”

There is no “current organization” header. Each call that acts on an organization names it, usually in the path:

Terminal window
curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/members" \
  -H "Authorization: Bearer $ELE_TOKEN"

A few calls take organization_id in the body or query instead. The reference page for each operation says where it goes. Calls on a single resource, such as GET /api/v1/approvals/{approval_id}, find the organization from the resource.

Listing organizations

Section titled “Listing organizations”

GET /api/v1/organizations lists the organizations the signed-in user belongs to. It returns pages of up to 100 (50 by default). Follow next_cursor until has_more is false.

Each organization in the list has:

  • role: the user’s role there, owner, admin or member.
  • permissions: the permission keys the user holds there, such as approvals.review.

Use permissions to decide what to show in your product. Do not decide from the role name: permissions can also come from grants to one member, such as card access. Ele checks every call anyway, and refuses one the user may not make with 403.

Roles

Section titled “Roles”

There are three roles: owner, admin and member. This table shows the main differences between them for the operations in this API.

What Permission key Owner Admin Member
Read the organization and its member list organization.read, members.list ✓ ✓ ✓
Read verification status and checklist summary organization.view_kyb_status, organization.view_capabilities ✓ ✓ ✓
See the full onboarding requirements onboarding.view_requirements ✓ ✓
Update the organization’s details, logo and settings organization.update, organization.update_logo, organization.update_preferences ✓ ✓
Read balances organization.view_balances ✓ ✓
See every transaction transactions.list_all ✓ ✓
See their own transactions transactions.list_own ✓ ✓ ✓
Create payments payments.send_fiat, payments.send_crypto ✓ ✓ ✓
Swap currencies payments.swap_fiat ✓ ✓
Approve or reject requests approvals.review ✓ ✓
Add and list payment contacts payment_contacts.create, payment_contacts.list ✓ ✓ ✓
Change or delete payment contacts payment_contacts.update, payment_contacts.delete ✓ ✓
Add or change payment destinations payment_destinations.create, payment_destinations.update ✓ ✓
List deposit addresses deposit_addresses.list ✓ ✓
Work with bills bills.* ✓ ✓ ✓
Create, send and read invoices billing_invoices.create, billing_invoices.submit, billing_invoices.read ✓ ✓ ✓
See every invoice, and match invoices to payments billing_invoices.list_all, billing_invoices.allocate ✓ ✓
Manage their own expenses expenses.manage_own ✓ ✓ ✓
Manage everyone’s expenses expenses.manage_all ✓ ✓
See and manage every card, and set card limits cards.list_all, cards.update_limit ✓ ✓
Approve members for cards card_entitlements.create ✓ ✓
Invite people, and manage invitations invitations.* ✓ ✓
Change a member’s role, or remove a member members.manage ✓ ✓
Manage API keys api_keys.manage ✓ ✓
Connect and disconnect integrations integrations.connect, integrations.disconnect ✓ ✓

Some card actions belong to the cardholder alone, whatever their role: activating a card, setting its PIN, ordering a physical card and adding it to a wallet. Anyone, whatever their role, needs card approval before they can create a card.

A role is not the only check. The organization must also be able to do the thing, which depends on how far it has got through verification and setup. GET /api/v1/organizations/{organization_id}/capabilities shows what an organization can do now.

Choosing roles for your staff

Section titled “Choosing roles for your staff”
  • Give admin to staff who approve payments or manage the organization.
  • Give member to staff who only prepare work, such as creating payments for someone else to approve.

An organization can require a second person to approve each request. Then a staff member cannot approve a payment they created themselves. See Step-up and approvals.

The owner role cannot be given by invitation or by changing a role. Ele’s support team transfers ownership.

Inviting staff to a client organization

Section titled “Inviting staff to a client organization”

An owner or admin of the client organization invites your staff member by email with POST /api/v1/organizations/{organization_id}/invitations:

Terminal window
curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/invitations" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"email": "staff@yourcompany.example", "role": "admin"}'

role is admin or member, and defaults to member. To invite several people at once, use POST /api/v1/organizations/{organization_id}/invitations/bulk.

The invitation’s status says what happens next:

status Meaning
pending Ele has emailed the invitation. It waits for the person to accept it before expires_at.
pending_approval The organization approves invitations first. Approve the request in approval_request_id (see Step-up and approvals), and Ele then sends the email.
accepted The person has joined.

The person accepts from the link in the email. If they do not have an Ele account yet, they create one as they accept. If you have the invitation token, POST /api/v1/invitations/accept accepts it for the signed-in user.

To see invitations that have not been accepted, use GET /api/v1/organizations/{organization_id}/invitations. To resend one, use POST /api/v1/invitations/{invitation_id}/resend.

Removing access

Section titled “Removing access”

When a staff member leaves your company, remove them from every client organization they belong to.