---
title: "Invite or add a person to a business"
method: POST
path: "/organization-roles"
tags: ["Organization Roles"]
---

# Invite or add a person to a business

`POST /organization-roles`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/organization-roles`
- Auth: HTTP bearer

Create a business membership or invitation with the requested permission
and status. Supply the `organization` relationship and identify the
person through a `user` relationship, `invited_email`, or
`invited_mobile`. Requires edit rights on the business; the assigned
permission cannot exceed the caller's own role.

Inviting by email or mobile may send an email or SMS. A matching
existing account is linked to the role; otherwise a pending invitation
carries a seven-day link. Confirm the business, person and permission
before creating the role. Returns the created membership or invitation.
This does not create a user account or accept an invitation for them.

## Query parameters

- `include` string

## Request body

- OrganizationRoleCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields and relationships live directly under `data` (no nested `attributes` / `relationships` envelopes). Each relationship is a resource identifier object ({ id, type }). Equivalent JSON:API (nested) shape: `OrganizationRoleCreateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `permission` 'owner' | 'admin' | 'manager' | 'contractor' | 'viewer'
    - `status` 'pending' | 'accepted' | 'declined', nullable
    - `invited_email` string, nullable: Invite by email when no existing user is linked. One of user / invited_email / invited_mobile identifies the invitee.
    - `invited_mobile` string, nullable: Invite by mobile when no existing user is linked.
    - `organization` object, nullable, required
      - `id` string, nullable
      - `type` 'organization', nullable
    - `user` object, nullable
      - `id` string, nullable
      - `type` 'user', nullable

## Response `201`

Created. When the `include` query parameter is used, the response may contain an `included` array (JSON:API) or inlined related resources (application/json).

- OrganizationRolesShowResponseAttributes
  - `data` OrganizationRoleModelAttributes: Organization role in attributes-adapter shape (Accept application/json); fields at top level.
    - `id` string
    - `type` string
    - `status` 'pending' | 'accepted' | 'declined'
    - `permission` 'owner' | 'admin' | 'manager' | 'contractor' | 'viewer'
    - `invited_email` string, nullable
    - `invited_mobile` string, nullable
    - `invited` boolean
    - `inviter_name` string: Display name of the inviter (the organization owner).
    - `updated_at` string, date-time
    - `created_at` string, date-time
    - `organization` object: Inlined when include=organization
    - `user` object: Inlined when include=user

## Other responses

- `401`: Unauthenticated
- `403`: Forbidden

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/a9136f78e9fb?raw)