Invite someone to a product

Invites someone without an Arbol account by email with a role in Raíz, Agenda, Ámbar or Account. The invitation email comes from the product's own application. Existing accounts receive access with members.create and sign in with their current password.

Scope: account:members:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 32 KB, response up to 256 KB
CLI: arbol account invitations create · MCP tool: account_invitations_create

POST

https://api.getarbol.com/v1/account/invitations

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope account:members:write. Get an API key.

Request body JSON required

email
string
required
Who to invite: someone who does not have an Arbol account yet.

format: email · maxLength: 320
product
raiz
or
agenda
or
ambar
or
account
required
A product whose team Account administers: Raíz, Agenda, Ámbar or Account itself.
role
string
required
A role name, such as calendar:operator.

maxLength: 128 · minLength: 1

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- id
  string
  required
  maxLength: 256 · minLength: 1
- email
  string
  required
  maxLength: 320
- roles
  array of
  object
  required
  product
  raiz
  or
  agenda
  or
  ambar
  or
  account
  required
  A product whose team Account administers: Raíz, Agenda, Ámbar or Account itself.
  
  role
  string
  required
  A role name, such as calendar:operator.
  
  maxLength: 128 · minLength: 1
- createdAt
  string
  required
  format: date-time
- expiresAt
  string
  required
  format: date-time
- revocable
  boolean
  required
  Whether the caller may revoke it.
}
error
unknown
required
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

success
false
required
data
unknown
required
error
object
required
The request does not match the published schema.
- code
  INVALID_INPUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  issues
  optional
  array of
  object
  path
  string
  required
  RFC 6901 JSON Pointer to the refused field; empty for the whole input.
  
  maxLength: 256
  message
  string
  required
  maxLength: 256
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

401

UNAUTHORIZED: A valid access token is required.

JSON

success
false
required
data
unknown
required
error
object
required
A valid access token is required.
- code
  UNAUTHORIZED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

403

FORBIDDEN: The token does not authorize this operation.
ROLE_NOT_ASSIGNABLE: You cannot assign this role.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
ForbiddenFailure
FORBIDDEN
code
FORBIDDEN
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountRoleNotAssignableFailure
ROLE_NOT_ASSIGNABLE
code
ROLE_NOT_ASSIGNABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

409

IDENTITY_REJECTED: The identity service refused the change.
MEMBER_EXISTS: This person is already a member.
ACCOUNT_EXISTS: This person already has an Arbol account. Give them access with members.create.
INVITATION_EXISTS: This person already has a pending invitation to this product.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
AccountIdentityRejectedFailure
IDENTITY_REJECTED
code
IDENTITY_REJECTED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountMemberExistsFailure
MEMBER_EXISTS
code
MEMBER_EXISTS
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountAccountExistsFailure
ACCOUNT_EXISTS
code
ACCOUNT_EXISTS
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountInvitationExistsFailure
INVITATION_EXISTS
code
INVITATION_EXISTS
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

success
false
required
data
unknown
required
error
object
required
The request exceeds the allowed size.
- code
  REQUEST_TOO_LARGE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

success
false
required
data
unknown
required
error
object
required
The request content type is not supported.
- code
  UNSUPPORTED_MEDIA_TYPE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

success
false
required
data
unknown
required
error
object
required
The request rate limit was exceeded. Try again later.
- code
  RATE_LIMITED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

success
false
required
data
unknown
required
error
object
required
The service could not complete the operation.
- code
  INTERNAL_ERROR
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

success
false
required
data
unknown
required
error
object
required
The operation may have been applied; check its result before repeating it.
- code
  OUTCOME_UNKNOWN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
ACCOUNT_NOT_CONFIGURED: Account administration is not configured yet.
IDENTITY_UNAVAILABLE: The identity service did not answer.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
UpstreamUnavailableFailure
UPSTREAM_UNAVAILABLE
code
UPSTREAM_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountAccountNotConfiguredFailure
ACCOUNT_NOT_CONFIGURED
code
ACCOUNT_NOT_CONFIGURED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

AccountIdentityUnavailableFailure
IDENTITY_UNAVAILABLE
code
IDENTITY_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service did not respond before its deadline.
- code
  UPSTREAM_TIMEOUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}