Invite a teammate by email

POST

/v1/members/invite

curl --request POST \
  --url http://localhost:8080/v1/members/invite \
  --header 'Content-Type: application/json' \
  --cookie hardcount_session=<hardcount_session> \
  --data '{ "email": "hello@example.com" }'

• Local development

Creates a pending invitation (7-day expiry, one pending per email) and sends the accept link via the transactional email outbox. Requires DASHBOARD_BASE_URL — accept links are never derived from request headers. 409 when the email is already a member or already has a pending invite. ADR-081.

Authorizations

• SessionCookie

Parameters

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

email

required

string format: email

Example ^generated

{
  "email": "hello@example.com"
}

Responses

201

Invitation created and email enqueued

Media typeapplication/json

object

id

required

string

email

required

string

role

required

Recorded for the future role split; not enforced (every member holds the full permission set).

string

status

required

Server-derived; treat as authoritative.

string

Allowed values: pending accepted revoked expired

invited_by_email

string

expires_at

required

string format: date-time

created_at

required

string format: date-time

accepted_at

string format: date-time

revoked_at

string format: date-time

Example

{
  "id": "hc_minv_1a2b3c4d5e6f7890",
  "status": "pending"
}

409

No invitation was created when the code is email_not_configured (this server has no SMTP set up, so the accept link could not be delivered) or invalid_state (DASHBOARD_BASE_URL is not set). Also returned when the email is already a member or already has a pending invitation.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

Invalid email

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}