---
title: "Add someone to a suite's directory"
description: "Create a directory entry; this grants no access."
canonical: "https://grid82.com/docs/builder-api/users/invite"
updated: "2026-11-13"
---

# Add someone to a suite's directory

`POST https://studio.grid82.app/v1/users`

Create a directory entry; this grants no access.

Add the user to an app with `members.add` afterwards. Directory membership and app access are separate so onboarding a colleague does not require deciding what they may see in the CRM.

Requires the `members:write` scope. Operation `users.invite`. MCP tool `users_invite`. CLI: `grid82 users invite` (`npx grid82`).

## Headers

| Name              | Type   | Required | Description                                                                                                                                                                                                                                                        |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | string | no       | Any unique string. Sending the same key with the same request again returns the first response (marked `Idempotency-Replayed: true`) instead of running it twice. Reusing it for a different request is refused with 409. Kept for 24 hours. Up to 255 characters. |

## Request body

| Field     | Type                  | Required | Description          |
| --------- | --------------------- | -------- | -------------------- |
| `suiteId` | string                | yes      | Up to 64 characters. |
| `email`   | string                | yes      |                      |
| `name`    | string                | no       | Up to 80 characters. |
| `kind`    | "builder" or "member" | no       | Default `"member"`.  |

**Authorizations**

- `Authorization` (bearer, in header, required)

## Response

**201**: Success

- `data` (`object`, required)
- `data.userId` (`string`, required)
- `data.email` (`string`, required)
- `data.status` (`string`, required)

```json
{
  "data": {
    "userId": "<string>",
    "email": "<string>",
    "status": "<string>"
  }
}
```

**4XX**: Refused

- `error` (`object`, required)
- `error.code` (`enum<string>`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`)
- `error.message` (`string`, required)
- `error.details` (`Record<string, unknown>`)

```json
{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}
```

**Example request**

```bash
curl --request POST \
  --url 'https://studio.grid82.app/v1/users' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "suiteId": "<string>",
  "email": "<string>"
}'
```