---
title: "Invite a team member"
url: https://docs.corefinity.com/api/recipes/invite-a-team-member
type: page
last_updated: 2026-11-13
feature: recipe-invite-a-team-member
---
# Invite a team member

Choose a role, invite a person to your company's team and check the invitation.

An invitation adds a person to your own company with one role and emails them a link to accept. This recipe invites Rosa Whitlock to Harbour & Finch.

## Before you start

- A token with the `read` and `write` [scopes](/api/scopes).
- You are an owner of your company, or your role has the `inviteUsers` permission. You can give only a role whose permissions you hold yourself.
- No step needs two-factor enrolment.
- No step waits for a maintenance window.

1. **List the roles you may give**

   The answer maps each role's slug to its name. Note the slug of the role to give.

   ```bash
   curl https://manage.corefinity.com/api/roles \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

2. **Send the invitation**

   Send the person's name, their email address and the role's slug. The invitation is emailed at once, and the answer is the same whether or not the address already has a Control Panel account.

   ```bash
   curl -X POST https://manage.corefinity.com/api/user/invite \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"name": "Rosa Whitlock", "email": "rosa.whitlock@harbourandfinch.example.com", "role": "client-member-full"}'
   ```

   The answer is `201`. Note `data.id`, the new member's id.

3. **Check the invitation**

   Search your team for the person. Until they accept, their `status` is `invite_sent` and `invitation_expires_at` says how long the link lasts; afterwards it is `active`.

   ```bash
   curl "https://manage.corefinity.com/api/team/members?search=rosa.whitlock" \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

4. **Send the invitation again**

   Only when the person did not get the email, or the link has expired. It emails them a new link and answers `200`.

   ```bash
   curl -X POST https://manage.corefinity.com/api/user/2044/resend-invite \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

## If it is refused

| Status | `reason`              | What to do                                                                                                                                               |
| ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `forbidden`           | You may not invite users. Ask an owner of your company for the `inviteUsers` permission                                                                  |
| `403`  | `owner_grant`         | Only an owner or Corefinity staff can invite somebody as an owner                                                                                        |
| `403`  | `permission_grant`    | The role carries a permission you do not hold yourself. Choose another role                                                                              |
| `422`  | `invalid`             | Correct the field named in `field` and `errors`: on `role`, a role you may not give in your company; on `email`, an address that is already on your team |
| `409`  | `invite_company_gone` | Your company is not active, so nobody can be invited yet                                                                                                 |
| `403`  | `already_active`      | The person has already accepted, so there is nothing to send again                                                                                       |
