> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Invitations

> Generate partner invitations for client WhatsApp Business onboarding via the Zavu Python SDK. Track status and manage expiration.

Partner invitations allow you to generate links for clients to connect their WhatsApp Business accounts to your project.

## Create Invitation

```python theme={null}
invitation = client.invitations.create(
    client_name="Acme Corp",
    client_email="contact@acme.com",
    expires_in_days=14
)

print(invitation.id)      # jh7am5bng9p3v2x1k4r8
print(invitation.url)     # https://dashboard.zavu.dev/invite/abc123xyz
print(invitation.status)  # pending
```

### With Phone Number Restrictions

Restrict which countries the client can register phone numbers from:

```python theme={null}
invitation = client.invitations.create(
    client_name="Acme Corp",
    client_email="contact@acme.com",
    expires_in_days=7,
    allowed_phone_countries=["US", "MX"]
)
```

## Get Invitation

```python theme={null}
result = client.invitations.get(invitation_id="jh7am5bng9p3v2x1k4r8")
invitation = result.invitation

print(invitation.status)       # pending | in_progress | completed | expired | cancelled
print(invitation.client_name)  # Acme Corp
print(invitation.sender_id)    # None (until completed)
print(invitation.expires_at)   # 2025-01-15T00:00:00.000Z
```

## List Invitations

```python theme={null}
result = client.invitations.list()

for invitation in result.items:
    print(invitation.id, invitation.client_name, invitation.status)
```

### Filter by Status

```python theme={null}
result = client.invitations.list(
    status="pending",
    limit=50
)
```

### Pagination

```python theme={null}
cursor = None

while True:
    result = client.invitations.list(
        limit=50,
        cursor=cursor
    )

    for invitation in result.items:
        print(invitation.id)

    if not result.next_cursor:
        break
    cursor = result.next_cursor
```

## Cancel Invitation

Cancel an active invitation to prevent the client from using it:

```python theme={null}
result = client.invitations.cancel(invitation_id="jh7am5bng9p3v2x1k4r8")
print(result.invitation.status)  # cancelled
```

<Note>
  You cannot cancel a completed invitation. Once a sender is created, manage it through the senders API.
</Note>

## After Completion

When a client completes the signup flow, a sender is created in your project:

```python theme={null}
result = client.invitations.get(invitation_id="jh7am5bng9p3v2x1k4r8")
invitation = result.invitation

if invitation.status == "completed" and invitation.sender_id:
    # Use the sender to send messages
    client.messages.send(
        to="+14155551234",
        channel="whatsapp",
        message_type="template",
        content={
            "template_id": "tmpl_xyz789",
            "template_variables": {
                "1": "John"
            }
        },
        extra_headers={
            "Zavu-Sender": invitation.sender_id
        }
    )
```

## Full Example

```python theme={null}
import os
from zavu import Zavu

client = Zavu(api_key=os.environ["ZAVU_API_KEY"])

def onboard_client(client_name: str, client_email: str):
    """Create an invitation for a new client."""
    invitation = client.invitations.create(
        client_name=client_name,
        client_email=client_email,
        expires_in_days=7
    )

    print(f"Send this link to {client_name}: {invitation.url}")
    return invitation

def check_invitation_status(invitation_id: str):
    """Check the status of an invitation."""
    result = client.invitations.get(invitation_id=invitation_id)
    invitation = result.invitation

    match invitation.status:
        case "pending":
            print("Waiting for client to start signup")
        case "in_progress":
            print("Client is completing the signup flow")
        case "completed":
            print(f"Success! Sender ID: {invitation.sender_id}")
        case "expired":
            print("Invitation expired, create a new one")
        case "cancelled":
            print("Invitation was cancelled")

    return invitation

# Usage
invitation = onboard_client("Acme Corp", "contact@acme.com")
# Later...
check_invitation_status(invitation.id)
```

## Async Usage

```python theme={null}
import asyncio
from zavudev import AsyncZavudev

async def main():
    client = AsyncZavudev()

    invitation = await client.invitations.create(
        client_name="Acme Corp",
        client_email="contact@acme.com",
        expires_in_days=7
    )
    print(invitation.url)

    # List pending invitations
    result = await client.invitations.list(status="pending")
    for inv in result.items:
        print(inv.client_name, inv.status)

asyncio.run(main())
```