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

# Invite Agent

> Add a team member to your organization by email.

Invites an existing PingBack user to join your organization as an agent or admin. Only the org owner can send invitations.

**Method**: `POST`  **URL**: `/api/v1/team/invite`

<Note>
  The person you are inviting must already have a PingBack account. If they do not have one, ask them to sign up at [pingback.live](https://pingback.live) first.
</Note>

### Plan limits

| Plan | Max agents               |
| ---- | ------------------------ |
| Free | 0 (no additional agents) |
| Mini | 2                        |
| Pro  | 5                        |

### Headers

| Header        | Value          |
| ------------- | -------------- |
| Authorization | Bearer {token} |

### Query parameters

<ParamField query="email" type="string" required>
  Email address of the PingBack user to invite. They must have an existing account.
</ParamField>

<ParamField query="role" type="string" default="agent">
  The role to assign. Must be `agent` or `admin`. The org owner is always `owner` and cannot be changed via this endpoint.
</ParamField>

### Response

<ResponseField name="message" type="string" required>
  Confirmation message indicating the invited user's role and email.
</ResponseField>

<ResponseField name="team_member_id" type="string" required>
  UUID of the newly created team membership record.
</ResponseField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://api.pingback.live/api/v1/team/invite?email=james@acme.com&role=agent' \
    --header 'Authorization: Bearer {token}'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ email: 'james@acme.com', role: 'agent' });

  const response = await fetch(
    `https://api.pingback.live/api/v1/team/invite?${params}`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer {token}'
      }
    }
  );

  const result = await response.json();
  ```
</CodeGroup>

### Response example

```json theme={null}
{
  "message": "Agent james@acme.com invited successfully",
  "team_member_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

***

## Assign a conversation

**Method**: `POST`  **URL**: `/api/v1/team/assign/{conversation_id}`

Assigns an open conversation to a specific agent. Only admins (org owner or members with the `admin` role) can assign conversations. The assigned agent receives an instant `conversation_assigned` Socket.IO event.

### Path parameters

<ParamField path="conversation_id" type="string" required>
  The UUID of the conversation to assign.
</ParamField>

### Query parameters

<ParamField query="agent_id" type="string" required>
  The `user_id` of the team member to assign the conversation to. The agent must be an active member of your organization.
</ParamField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://api.pingback.live/api/v1/team/assign/conv-uuid-here?agent_id=agent-user-uuid' \
    --header 'Authorization: Bearer {token}'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ agent_id: 'agent-user-uuid' });

  await fetch(
    `https://api.pingback.live/api/v1/team/assign/conv-uuid-here?${params}`,
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer {token}' }
    }
  );
  ```
</CodeGroup>

### Response example

```json theme={null}
{ "message": "Conversation assigned successfully" }
```

### Errors

| Status | Meaning                                                                                       |
| ------ | --------------------------------------------------------------------------------------------- |
| 400    | User is already a team member, invalid role, or agent is not a team member                    |
| 401    | Unauthorized — missing or invalid token                                                       |
| 402    | Plan limit reached — upgrade to add more agents                                               |
| 403    | Forbidden — only the org owner can invite team members / only admins can assign conversations |
| 404    | User not found — they must have a PingBack account first / conversation not found             |