Skip to content

Organizations

The Organizations resource provides methods to manage organization members and invitations.

Initialization

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

List Organization Users

Retrieve a list of all users in an organization.

Method

client.organizations.list_users(organization_id: str) -> list[User]

Parameters

Parameter Type Required Description
organization_id str Yes The organization ID

Returns

List of User objects.

Example

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

# Get current user to find organization ID
user = client.users.me()

# List all users in the organization
users = client.organizations.list_users(organization_id=user.organization_id)

for member in users:
    print(f"User: {member.full_name} ({member.email})")
    print(f"  Plan: {member.subscription_plan.value}")

Official Reference

List Organization Users

Remove Organization User

Remove a user from an organization.

Method

client.organizations.remove_user(
    organization_id: str,
    user_id: str
) -> None

Parameters

Parameter Type Required Description
organization_id str Yes The organization ID
user_id str Yes The user ID to remove

Returns

None (successful removal returns no content)

Example

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

# Remove a user from the organization
client.organizations.remove_user(
    organization_id="org_abc123",
    user_id="usr_xyz789"
)

print("User removed successfully")

Errors

Exception Status Code Description
NotFoundError 404 Organization or user not found
ForbiddenError 403 Insufficient permissions

Official Reference

Remove Organization User

List Organization Invites

Retrieve all pending invitations for an organization.

Method

client.organizations.list_invites(organization_id: str) -> list[Invite]

Parameters

Parameter Type Required Description
organization_id str Yes The organization ID

Returns

List of Invite objects.

Example

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

# List all pending invites
invites = client.organizations.list_invites(organization_id="org_abc123")

for invite in invites:
    print(f"Invite ID: {invite.id}")
    print(f"Email: {invite.email}")
    print(f"Status: {invite.status}")
    print(f"Sent: {invite.created_at}")

Official Reference

List Organization Invites

Create Organization Invites

Send invitations to join an organization.

Method

client.organizations.create_invites(
    organization_id: str,
    emails: list[str]
) -> list[Invite]

Parameters

Parameter Type Required Description
organization_id str Yes The organization ID
emails list[str] Yes List of email addresses to invite

Returns

List of created Invite objects.

Example

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

# Invite multiple users
invites = client.organizations.create_invites(
    organization_id="org_abc123",
    emails=[
        "[email protected]",
        "[email protected]"
    ]
)

for invite in invites:
    print(f"Invited: {invite.email}")
    print(f"Invite ID: {invite.id}")

Errors

Exception Status Code Description
BadRequestError 400 Invalid email format or duplicate invites
ForbiddenError 403 Insufficient permissions

Example with Error Handling

from tally import Tally, BadRequestError

client = Tally(api_key="tly_your_api_key_here")

try:
    invites = client.organizations.create_invites(
        organization_id="org_abc123",
        emails=["[email protected]"]
    )
    print(f"Invitation sent successfully!")
except BadRequestError as e:
    print(f"Failed to send invite: {e.message}")
    for error in e.errors:
        print(f"  - {error}")

Official Reference

Create Organization Invites

Cancel Organization Invite

Cancel a pending organization invitation.

Method

client.organizations.cancel_invite(
    organization_id: str,
    invite_id: str
) -> None

Parameters

Parameter Type Required Description
organization_id str Yes The organization ID
invite_id str Yes The invite ID to cancel

Returns

None (successful cancellation returns no content)

Example

from tally import Tally

client = Tally(api_key="tly_your_api_key_here")

# Cancel a pending invite
client.organizations.cancel_invite(
    organization_id="org_abc123",
    invite_id="inv_xyz789"
)

print("Invite cancelled successfully")

Errors

Exception Status Code Description
NotFoundError 404 Invite not found

Official Reference

Cancel Organization Invite

Models

Invite Model

Invite dataclass

Represents a Tally organization invite.

Example:

Invite(
    id="inv_abc123",
    email="[email protected]",
    status="pending",
    created_at="2024-01-15T10:30:00Z"
)

Complete Example

from tally import Tally, BadRequestError, NotFoundError

client = Tally(api_key="tly_your_api_key_here")

# Get organization ID from current user
user = client.users.me()
org_id = user.organization_id

# List current members
print("Current members:")
members = client.organizations.list_users(organization_id=org_id)
for member in members:
    print(f"  - {member.full_name} ({member.email})")

# Send invitations
try:
    print("\nSending invitations...")
    invites = client.organizations.create_invites(
        organization_id=org_id,
        emails=["[email protected]"]
    )
    print(f"Sent {len(invites)} invitation(s)")
except BadRequestError as e:
    print(f"Failed to send invites: {e.message}")

# List pending invites
print("\nPending invites:")
invites = client.organizations.list_invites(organization_id=org_id)
for invite in invites:
    print(f"  - {invite.email} (ID: {invite.id})")

# Cancel an invite if needed
if invites:
    try:
        client.organizations.cancel_invite(
            organization_id=org_id,
            invite_id=invites[0].id
        )
        print(f"\nCancelled invite for {invites[0].email}")
    except NotFoundError:
        print("Invite not found")

Next Steps