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

# Inviting members

> Invite people to your organisation by OSAID with a role, record who each invitation is for, and follow the answers.

The people of your organisation in OSA are its **members**. An adjuster can receive claims from you only after accepting your invitation. You invite a person by their **OSAID**, the account id on their profile in the OSA app (the field labelled OSA ID, which has a copy button). Copy it exactly: capital and small letters matter. An OSAID exists once the person has signed in to the app, so someone who isn't on OSA yet installs the app and creates an account first. An invitation can't be sent to an email address.

## Send an invitation

```bash theme={"system"}
curl https://api.osaconnection.com/v1/members/invitations \
  -H "Authorization: Bearer $OSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "osa_id": "Hp2sK8dL4fJ6gA1zX9cV3bN7mQ5w",
    "role": "adjuster",
    "invited_as": "Todd Rivera",
    "invited_by": "Dana Whitfield, Claims Operations",
    "purpose": "Flood claims in the Tampa Bay area this season.",
    "note": "Referred by Jordan Ellis."
  }'
```

`osa_id` and `role` are required. The person sees the invitation in the OSA app and accepts or declines it. An invitation that isn't answered expires after 7 days. The invitation shows the person your organisation's name and `invited_as`. Nothing about your claims reaches them until they accept.

## Roles

`role` is required. It is OSA's **role kind**, not your own title for the role. Which roles you can invite depends on your partner type and your setup with OSA. Today: `adjuster`.

Any other value, including a different spelling such as `"Adjuster"`, is refused with `422 validation_failed`.

## Your notes

Four optional fields record who an invitation is for and why. To send no note, leave the field out: `null` and an empty string are refused with `422 validation_failed`.

| Field | Length | Meaning |
| - | - | - |
| `invited_as` | Up to 200 characters | Who you believe you are inviting, for example the person's name |
| `invited_by` | Up to 200 characters | Who in your organisation sent the invitation |
| `purpose` | Up to 500 characters | What the invitation is for |
| `note` | Up to 1,000 characters | Anything else you want to record with the invitation |

* **They are your own notes.** Nothing is checked against the person's account, and no invitation is refused because of them. Whoever owns the OSAID can accept.
* **The person sees `invited_as`** on the invitation in the app. The other three are for you only.
* **They are returned whenever members are listed.** Each member in `GET /v1/members` carries all four, and so do the responses to sending and withdrawing an invitation. A note you didn't send is `null`.
* **Inviting again replaces them.** A new invitation to the same person replaces all four with whatever it sends. A note the new invitation leaves out becomes `null`.

## What the person needs before accepting

The person must have a **first name, a last name and an email** on their OSA profile before they can accept an invitation. If one is missing, the invitation can't be accepted until they complete their profile in the app.

If someone tells you they can't accept, ask them to check their profile in the OSA app.

## Follow the invitation

```bash theme={"system"}
curl https://api.osaconnection.com/v1/members \
  -H "Authorization: Bearer $OSA_API_KEY"
```

```json theme={"system"}
{
  "data": [
    {
      "osa_id": "Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j",
      "status": "active",
      "roles": ["adjuster"],
      "test": false,
      "name": "Jordan Ellis",
      "email": "jordan.ellis@example.com",
      "invited_at": "2026-09-01T16:20:00Z",
      "expires_at": null,
      "responded_at": "2026-09-01T18:44:12Z",
      "invited_as": "Jordan Ellis",
      "invited_by": "Dana Whitfield, Claims Operations",
      "purpose": "Flood claims in the Tampa Bay area this season.",
      "note": null
    },
    {
      "osa_id": "Hp2sK8dL4fJ6gA1zX9cV3bN7mQ5w",
      "status": "pending",
      "roles": ["adjuster"],
      "test": false,
      "name": null,
      "email": null,
      "invited_at": "2026-09-28T13:02:45Z",
      "expires_at": "2026-10-05T13:02:45Z",
      "responded_at": null,
      "invited_as": "Todd Rivera",
      "invited_by": "Dana Whitfield, Claims Operations",
      "purpose": "Flood claims in the Tampa Bay area this season.",
      "note": "Referred by Jordan Ellis."
    }
  ],
  "next_cursor": null
}
```

| `status` | Meaning |
| - | - |
| `pending` | Invited, not yet answered |
| `active` | Accepted, and a member of your organisation |
| `declined` | The person declined |
| `expired` | Not answered within 7 days |
| `withdrawn` | You withdrew the invitation |

`roles` is a list of role kinds, because a person can hold more than one role. Everyone invited through the API has `adjuster`. A person whose roles in your organisation have no kind (for example, roles set up for your organisation before role kinds existed) is listed with an empty list, `[]`.

`name` and `email` are `null` until the person accepts. After that they are the account's own name and email. `invited_as` stays what you wrote, so it can differ from `name`: compare the two if you need to confirm that the person you meant to invite is the one who accepted.

A member can leave your organisation in the app. One who has left no longer appears in the list, under any status. Claims an adjuster had already accepted stay with them; new claims sent to them are refused with `422 adjuster_not_a_member`. Invite them again to bring them back.

Statuses and role kinds are open enums: handle values you don't recognise without failing.

## Inviting again and withdrawing

* You can invite someone again after they declined, after the invitation expired, or after you withdrew it.
* Inviting a current member returns `409 already_member`. Inviting someone whose invitation is still pending returns `409 invitation_pending`.
* `DELETE /v1/members/invitations/{osa_id}` withdraws a pending invitation.

## Test accounts

A test key can only invite your test accounts, and a live key can't invite them. See [Testing with test accounts](https://docs.osaconnection.com/testing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.