Create a staff invitation | Sailor API Docs

const url = 'https://api.sailorhq.io/staff/invites';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'Idempotency-Key',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"email":"agent@example.com","role":"agent","team_ids":["00000000-0000-4000-8000-000000000012"]}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "ok": true,
  "staff_invite": {
    "id": "00000000-0000-4000-8000-000000000010",
    "email": "agent@example.com",
    "role": "agent",
    "subaccount_id": "00000000-0000-4000-8000-000000000011",
    "team_ids": [
      "00000000-0000-4000-8000-000000000012"
    ],
    "status": "email_sent",
    "expires_at": "2026-08-18T00:00:00.000Z"
  }
}

Creates or renews one Sailor staff invitation pinned to the credential’s workspace. Organization and subaccount identifiers are derived server-side and cannot be supplied by the caller.

Authentication

AuthorizationBearer

Workspace API key created in Sailor Settings > Integrations > API access.

Request

This endpoint expects an object.

emailstringRequiredformat: "email"<=254 characters

roleenumRequired

Allowed values:

team_idslist of stringsOptional

Response headers

X-Request-IdstringOptional

Stable request identifier for support and observability.

RateLimit-PolicystringOptional

Versioned structured quota policy. The syntax follows IETF RateLimit draft 11 and may evolve before standardization.

RateLimitstringOptional

Current structured quota state for the authenticated credential.

Idempotent-ReplayedstringOptional

True when this exact response was replayed from a completed idempotency record.

Response

The tenant-pinned Sailor staff invitation is ready.

oktrue

staff_inviteobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

413

Content Too Large Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error

Authentication

Headers

Request

Response headers

Response

Errors