Staff automation

Create a staff invitation

The staff API creates or renews a tenant-pinned Sailor staff invitation in the exact workspace owned by the API key. The invited person becomes a Sailor staff member after accepting the invitation.

Sailor derives the organization and subaccount from the API key. Neither identifier can be supplied or overridden in the request.

Request

The API key needs the staff:write scope. Send a unique Idempotency-Key for each intended invitation.

$curl https://api.sailorhq.io/staff/invites \
>  --request POST \
>  --header "Authorization: Bearer $SAILOR_API_KEY" \
>  --header "Content-Type: application/json" \
>  --header "Idempotency-Key: $SAILOR_IDEMPOTENCY_KEY" \
>  --data '{
>    "email": "agent@example.com",
>    "role": "agent",
>    "team_ids": ["00000000-0000-4000-8000-000000000012"]
>  }'
FieldRequiredDescription
emailYesInvitation recipient. Sailor normalizes it to lowercase.
roleYesadmin or agent.
team_idsNoUp to 100 unique Sailor team IDs from the API key’s workspace.

Unknown fields are rejected. A caller cannot provide organization, subaccount, or external-system identifiers.

Response

1{
2  "ok": true,
3  "staff_invite": {
4    "id": "00000000-0000-4000-8000-000000000010",
5    "email": "agent@example.com",
6    "role": "agent",
7    "subaccount_id": "00000000-0000-4000-8000-000000000011",
8    "team_ids": ["00000000-0000-4000-8000-000000000012"],
9    "status": "email_sent",
10    "expires_at": "2026-08-18T00:00:00.000Z"
11  }
12}

email_delivery_failed means the tenant-pinned invitation exists but its email needs to be resent from Sailor. It does not mean the invitation was lost.

Recovery

CodeMeaningRecovery
invalid_requestThe email, role, body, or a team ID is invalid for this workspace.Correct the request and use a new idempotency key.
resource_conflictThe email is already an active member or a concurrent invitation won.Use Sailor staff access controls or resend the existing invitation.
temporarily_unavailableSailor could not persist or verify the invitation.Wait for Retry-After, then retry.

If Sailor returns 409 request_in_progress, retry with the same key after Retry-After. A completed response is replayed exactly for that key.

Create one key per automation and grant only staff:write when it manages only Sailor staff invitations.