Skip to main content
POST
Add a pod membership
Adds an active Employee or Contractor worker seat to a pod as lead or member from startsAt (a UTC day boundary), with an optional endsAt, allocationPercent (default 100) and deliveryRole. Returns 201 with the new membership. Send the pod’s current membershipRevision from Get pod as expectedMembershipRevision; a stale value returns 409 ending (POD_ROSTER_CHANGED). The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the membership; otherwise 403 naming workforce:read, and nothing changes. A pod whose managing org unit is a customer organization or sits under one returns 404, exactly as a missing pod. Send an Idempotency-Key to make a retry safe.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

podId
string
required

The pod's ID.

Minimum string length: 1

Body

application/json
workerId
string
required

An active Employee or Contractor worker seat linked to a person.

Minimum string length: 1
role
enum<string>
required
Available options:
lead,
member
startsAt
integer
required

When the membership starts (a UTC day boundary), epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
expectedMembershipRevision
integer
required

The pod's membershipRevision you last read (GET /api/v2/workforce/getPod).

Required range: x >= 0
allocationPercent
number

Whole percent of the person's capacity, 1 through 100 (the command enforces it).

deliveryRole
string
endsAt
integer

When the membership ends (a UTC day boundary), epoch milliseconds.

Required range: 0 <= x <= 9007199254740991

Response

Success

data
object
required
meta
object
required