Brand key required

Roster

Your active creator network. Creators land here when you hire an applicant, add one by email, or add one by social handle (the handle route scrapes their profile for you).

List your roster

GET/v1/roster

Deduplicated by creator email and enriched with social handles and affiliate stats. Standard page/limit pagination.

request

curl "https://api.ugcroster.com/v1/roster?limit=50" \
  -H "Authorization: Bearer rsk_brand_key"

response 200

{
  "data": [
    {
      "id": "hire_001",
      "email": "emma@example.com",
      "name": "Emma Chen",
      "user_id": "user_123",
      "form_id": "form_xyz789",
      "expected_videos": 2,
      "status": "hired",
      "hired_at": "2026-06-01T12:00:00Z",
      "instagram_handle": "emmachen",
      "tiktok_handle": "emmachen",
      "youtube_handle": null,
      "total_paid": 697.50,
      "content_delivered": 0
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 42, "has_more": false }
}

Add by email

POST/v1/roster

Field	Type	Description
creator_email	string	Required. Must contain @. Lowercased on write.
creator_name	string	Optional display name.

request

curl -X POST "https://api.ugcroster.com/v1/roster" \
  -H "Authorization: Bearer rsk_brand_key" \
  -H "Content-Type: application/json" \
  -d '{ "creator_email": "emma@example.com", "creator_name": "Emma Chen" }'

response 200

{ "data": { "id": "hire_002", "email": "emma@example.com", "name": "Emma Chen" } }

Adding an email already on your roster is not an error: the response is { "data": { "id": "hire_001", "already_hired": true } }with the existing entry’s ID.

Add by social handle

POST/v1/roster/add

No email required. Accepts bare handles, @handles, or full profile URLs, and auto-scrapes the profile picture, display name, and follower counts.

Field	Type	Description
ig_handle	string	Instagram handle or URL. Required unless tt_handle is set.
tt_handle	string	TikTok handle or URL. Required unless ig_handle is set.
name	string	Optional; auto-detected from the profile when omitted.
tags	string[]	Optional labels, e.g. ["skincare", "lifestyle"].

request

curl -X POST "https://api.ugcroster.com/v1/roster/add" \
  -H "Authorization: Bearer rsk_brand_key" \
  -H "Content-Type: application/json" \
  -d '{ "ig_handle": "@emmachen", "tt_handle": "@emmachen", "tags": ["skincare"] }'

response 201

{
  "data": {
    "id": "hire_003",
    "name": "Emma Chen",
    "ig_handle": "emmachen",
    "tt_handle": "emmachen",
    "pfp_url": "https://storage.googleapis.com/…",
    "ig_followers": 245000,
    "tt_followers": 89000,
    "engagement_rate": null,
    "tags": ["skincare"],
    "status": "hired"
  }
}

Update a roster entry

PATCH/v1/roster

Addressed by creator_email, not by ID. Updates fields on the entry, or refreshes the profile picture from the creator’s socials via the action field.

Field	Type	Description
creator_email	string	Required. Which roster entry to update.
action	string	Optional. "refresh-pfp" re-scrapes the profile picture (and name, if missing) from the stored IG/TikTok handles. 422 if the entry has no handles.
name	string	New display name.
expected_videos	integer	Number of videos expected from this creator.
tags	string[]	Replaces the tag list.
pfp_url	string	Set the profile picture URL directly.

request

curl -X PATCH "https://api.ugcroster.com/v1/roster" \
  -H "Authorization: Bearer rsk_brand_key" \
  -H "Content-Type: application/json" \
  -d '{ "creator_email": "emma@example.com", "expected_videos": 3, "tags": ["skincare", "fall-launch"] }'

response 200

{
  "data": {
    "id": "hire_001",
    "email": "emma@example.com",
    "expected_videos": 3,
    "tags": ["skincare", "fall-launch"]
  }
}

Errors

Status	Type	Description
409 ALREADY_EXISTS	roster/add	A creator with the same IG or TikTok handle is already on the roster. The response data echoes the existing handles.
404 NOT_FOUND	PATCH	No roster entry with that creator_email.
422 VALIDATION_ERROR	any	Missing creator_email, no handle on roster/add, or no valid fields to update.
403 FORBIDDEN	auth	The key cannot act on this brand’s roster (wrong key type or team).

Applications →

Hiring an applicant also creates a roster entry.

Briefs →

Send briefs to roster creators.

Creator search →

Find creators to add: 1,000,000+ profiles.