Skip to main content
POST
Assign a Customer to a pod
Assigns an active Organization Customer to an active pod for allocationPercent (1–100) of the pod’s capacity from startsAt (a UTC day boundary), with an optional endsAt and optional deliverySlices. Returns 201 with the assignment. A Customer has at most one assignment to a pod at a time (409 ending (POD_CUSTOMER_DATE_CONFLICT)), the pod’s assignments never exceed 100% at any moment ((POD_CUSTOMER_CAPACITY_EXCEEDED)), and an assignment cannot overlap the pod’s internal profile ((POD_INTERNAL_PROFILE_CONFLICT)). An unknown Customer returns 404; a person Customer, or an inactive or archived one, returns 409. A pod whose managing org unit is a customer organization or sits under one returns 404, exactly as a missing pod, and so does any assignment of such a pod or an assignment ID that does not resolve. The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the written row; otherwise 403 naming workforce:read, and nothing changes. workforce:manage must be held at the platform scope; no customers:read is needed. Send an Idempotency-Key to make a retry safe; a same-key retry returns the recorded result only while the scopes, the platform workforce:manage and the pod’s visibility still hold, otherwise 409 idempotency_result_unavailable.

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
customerId
string
required

An active Organization Customer.

Minimum string length: 1
allocationPercent
number
required

Whole percent from 1 through 100 of the pod's capacity.

startsAt
integer
required

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

Required range: 0 <= x <= 9007199254740991
deliverySlices
object[]

How the allocation splits by delivery type, category and stage.

endsAt
integer

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

Required range: 0 <= x <= 9007199254740991

Response

Success

data
object
required
meta
object
required