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

# Invitations

> API endpoints for managing invitations

## Get Public Invitation

<api-endpoint method="GET" path="/invitations/{id}" />

Get a public invitation by its ID. This endpoint does not require authentication and is used to display invitation details to potential users.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the invitation
</ParamField>

### Response

<ResponseField name="id" type="string">
  Invitation unique identifier
</ResponseField>

<ResponseField name="email" type="string">
  Email address the invitation was sent to
</ResponseField>

<ResponseField name="organization_id" type="string">
  ID of the organization for this invitation
</ResponseField>

<ResponseField name="project_id" type="string" optional>
  ID of the project for this invitation (if applicable)
</ResponseField>

<ResponseField name="organization_role" type="string">
  Role in the organization (OWNER, ADMIN, MEMBER, VIEWER)
</ResponseField>

<ResponseField name="project_role" type="string" optional>
  Role in the project (OWNER, ADMIN, MEMBER, VIEWER)
</ResponseField>

<ResponseField name="created_at" type="string">
  When the invitation was created (ISO 8601 format)
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the invitation was last updated (ISO 8601 format)
</ResponseField>

<ResponseField name="organization" type="object">
  Organization details

  <Expandable title="Organization Object">
    <ResponseField name="id" type="string">
      Organization unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Organization name
    </ResponseField>

    <ResponseField name="address_line1" type="string" optional>
      First line of organization address
    </ResponseField>

    <ResponseField name="address_line2" type="string" optional>
      Second line of organization address
    </ResponseField>

    <ResponseField name="zipcode" type="string" optional>
      Organization postal/zip code
    </ResponseField>

    <ResponseField name="state" type="string" optional>
      Organization state/province
    </ResponseField>

    <ResponseField name="country" type="string" optional>
      Organization country
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the organization was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the organization was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="project" type="object" optional>
  Project details (if invitation is for a specific project)

  <Expandable title="Project Object">
    <ResponseField name="id" type="string">
      Project unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Project name
    </ResponseField>

    <ResponseField name="description" type="string" optional>
      Project description
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      ID of the organization this project belongs to
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the project was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the project was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/invitations/inv_123'
  ```

  ```javascript JavaScript theme={null}
  const invitationId = 'inv_123';
  const response = await fetch(`https://api.plaisolutions.com/invitations/${invitationId}`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    }
  });

  const invitation = await response.json();
  console.log(invitation);
  ```

  ```python Python theme={null}
  import requests

  invitation_id = "inv_123"
  url = f"https://api.plaisolutions.com/invitations/{invitation_id}"
  headers = {
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  invitation = response.json()
  print(invitation)
  ```
</CodeGroup>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "id": "inv_123",
    "email": "user@example.com",
    "organization_id": "org_456",
    "project_id": "proj_789",
    "organization_role": "MEMBER",
    "project_role": "MEMBER",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "organization": {
      "id": "org_456",
      "name": "Acme Corp",
      "address_line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94105",
      "country": "USA",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-10T15:30:00Z"
    },
    "project": {
      "id": "proj_789",
      "name": "AI Assistant Project",
      "description": "Building an intelligent assistant",
      "organization_id": "org_456",
      "created_at": "2024-01-05T14:20:00Z",
      "updated_at": "2024-01-12T09:45:00Z"
    }
  }
  ```
</ResponseExample>

***

## Use Cases

### Invitation Flow

The invitation system follows this typical flow:

<Steps>
  <Step title="Send Invitation">
    An organization admin creates an invitation using the [`POST /organizations/{organization_id}/invitations`](organizations#add-invitation) endpoint
  </Step>

  <Step title="Share Invitation Link">
    The invitation link is shared with the recipient via email or other communication channels
  </Step>

  <Step title="View Invitation">
    The recipient uses this `GET /invitations/{id}` endpoint to view invitation details before accepting
  </Step>

  <Step title="Accept/Decline">
    The recipient uses the [`POST /me/invitations/{invitation_id}/reply`](me#reply-to-invitation) endpoint to accept or decline
  </Step>
</Steps>

### Security Considerations

<Warning>
  This endpoint is public and does not require authentication. However, invitation IDs should be treated as sensitive and not shared publicly as they provide access to organization information.
</Warning>

<Note>
  Invitations have expiration periods and can be revoked by organization administrators at any time.
</Note>

### Error Responses

<ResponseField name="404" type="error">
  Invitation not found or has been revoked
</ResponseField>

<ResponseField name="410" type="error">
  Invitation has expired
</ResponseField>

<CodeGroup>
  ```json 404 - Not Found theme={null}
  {
    "error": "Invitation not found",
    "message": "The invitation with ID 'inv_123' does not exist or has been revoked."
  }
  ```

  ```json 410 - Gone theme={null}
  {
    "error": "Invitation expired",
    "message": "This invitation has expired and is no longer valid."
  }
  ```
</CodeGroup>