Skip to main content
POST
Adds memberships to a custom list. Slugs are looked up in the people graph; an unknown slug is reported in meta.missing and does not create a membership. URLs are accepted even when the graph lookup does not find a person, so an arbitrary non-empty URL can create a membership with nullable person metadata. The operation processes slugs first and urls second. It is not transactional: a later lookup or database failure can leave earlier items written. Each item is an upsert keyed by the exact trimmed person_linkedin_url within the list.
string
required
List UUID or case-insensitive name. Default lists reject writes with 403; add members only to a custom list.
string[]
Optional LinkedIn public identifiers. If present, 1–100 non-validated strings. Unknown slugs are returned in meta.missing.
string[]
Optional URL strings, 1–100 items. The Gateway trims each value, extracts a slug from /in/<slug> when present, and otherwise stores the trimmed string as the membership URL. Empty trimmed values are skipped.
string
Optional enum: to-contact (default), contacted, responded, or passed.
string
Optional notes, up to 2,000 characters. Defaults to "" and is not nullable in the stored/API membership shape.
At least one of slugs or urls must contain a processable value. The body allows both arrays; the per-array maximum is 100, so a request can contain up to 200 entries. Only documented fields are supported; the framework strips unknown top-level fields.

Partial success and repeat calls

If the exact URL already belongs to the list, the existing membership is updated rather than duplicated. The supplied stage and notes always overwrite the existing values, including the defaults when those fields are omitted. Repeating a request can therefore reset a member’s stage to to-contact and notes to "". Enrichment fields are updated only when the new lookup supplies non-null values.

Response schema

A successful request returns 201: Each data item uses the membership shape from Get list: UUID id/list_id, required person_linkedin_url, nullable person enrichment fields, stage enum, string notes, and ISO added_at/updated_at timestamps.

Errors, reconciliation, and retry safety

  • 400: invalid body, invalid stage, no processable slugs/urls, or a missing platform-key X-FreshTalent-Org-Id UUID. Fix the request/header. A body containing an unknown slug can still return 201 with that slug in meta.missing.
  • 401 (unauthorized): provide a valid API key.
  • 402 (payment_required): restore entitlement.
  • 403 (forbidden): the addressed list is a Gateway-managed default list; use a custom list.
  • 404 (not_found): the list UUID/name is not visible to the organization.
  • 429 or 5xx: the outcome can be unknown and the request can be partially applied. Do not blindly replay a request that includes stage/notes. First GET /lists/{id} and reconcile by exact person_linkedin_url; retry only missing items with the intended stage and notes.
There is no request id or next link. The batch is bounded by the request arrays, not paginated.

Next steps

Get list to reconcile memberships, or Update list member for a stage/notes-only change.