Skip to main content
POST
Creates a custom list for the authenticated organization. The Gateway inserts a new row and returns it with member_count: 0, is_default: false, and null generated-list references. This endpoint does not add members and does not provide an idempotency key or upsert mode.
string
required
List name. Must contain 1–80 characters. The Gateway trims surrounding whitespace before storing it. Names are not enforced as unique by this route or its database insert.
string
Optional description, up to 400 characters. Omit it for null; an empty string is stored as null after trimming. Send a string when setting it. The current framework can coerce null to an empty string; do not use coercion as your client contract.
The JSON body is an object with only name and description; unknown top-level fields are stripped by the framework.

Response schema

data is a list object with the fields below. Timestamps are ISO 8601 strings.

Errors, side effects, and retry safety

  • 400: request-schema failure, such as a missing name, a name longer than 80 characters, a description longer than 400 characters, or a missing platform-key X-FreshTalent-Org-Id UUID. Fix the body/header before retrying.
  • 401 (unauthorized): provide a valid API key.
  • 402 (payment_required): restore the organization’s entitlement before retrying.
  • 429: back off and retry only after considering whether the first request may have succeeded.
  • 5xx: the outcome may be unknown. This POST is not idempotent; a retry can create another list, because the route always inserts and does not enforce name uniqueness. Reconcile with GET /lists and use the returned UUIDs before retrying.
A successful 201 has no pagination metadata and no next link. Add people separately with Add list members.

Next steps

Add list members or Get list.