Create Collab Scene

POST /api/v1/collab-scenes: open a multi-performer scene with per-scene consent collection.

The uploader is the producer. Whoever this call is made for is recorded as the 18 U.S.C. § 2257 primary producer, and Easy2257 is Custodian of Records. Content stays on your platform until the collab_scene.greenlit webhook fires.

Not idempotent. Every call creates a new scene, emails every performer, and charges fees: $5 per scene (500 cents), plus $25 (2500 cents) for each performer who does not already have an active Easy2257 account or an approved ID check from a collab scene in the last 12 months. The $25 is once per person, not once per scene. Guard it behind your own dedupe key.

On a platform-funded account, collab scenes bill your platform invoice. If your partner account pays for its creators, Easy2257 switches collab scenes on per account. Once it has, the fees above go on your platform's next monthly invoice instead of the creator's card: fees.billedTo reads platform_invoice, and charged stays false because nothing is taken when the scene is created. Until it is switched on, this call returns 409 with code collab_scenes_not_available_on_platform_pays before anything is created; log each creator's own uploads through POST /api/v1/solo-accounts/{accountId}/content and ask Easy2257 to switch collab scenes on. A switched-on account with no active or past-due platform fee subscription gets 409 collab_platform_billing_unavailable, also before anything is created.

Authorization

BearerAuth

AuthorizationBearer <token>

Partner API key from partner.easy2257.com/api-keys. Only ez_live_ keys are accepted. A key beginning with ez_test_ is rejected with 403 and code TEST_MODE_UNAVAILABLE before any handler runs: there is no sandbox, and every handler writes production records, provisions real users, and sends real email. New partner accounts start with a test key, so create a live key before your first call.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

uploaderAccountId?string

The accountId Easy2257 issued when you provisioned the uploader's solo account. Send exactly one of uploaderAccountId or uploaderExternalUserId. Either must resolve to an active solo account under your partner account, otherwise the call returns 400 with code uploader_not_solo_active.

uploaderExternalUserId?string

Your own user id for the uploader, exactly as you supplied it as externalUserId at provisioning. Alternative to uploaderAccountId; send one or the other, never both.

title*string

Lengthlength <= 500

shootDate?string

Formatdate-time

performers*array<>

1 to 10 performers, addresses unique within the request. Easy2257 emails each one a magic link. A performer who already has an active Easy2257 solo account signs and is done at no extra charge; so does returning collab talent whose approved ID check is from the last 12 months. Anyone else completes registration and ID verification inside the same link at 2500 cents, once per person. The response never says which path an individual performer is on.

Items1 <= items <= 10

uploaderAttestation*

All four fields required. Capture them from a real click event in your UI: this is the producer attestation, and a synthesized one is worth nothing in an inspection.

callbackUrl*string

Required, and stored for your reference only. Scene events go to the endpoints registered in the partner portal.

Formaturi

Response Body

`application/json`

curl -X POST "https://easy2257.com/api/v1/collab-scenes" \  -H "Content-Type: application/json" \  -d '{    "title": "April 2026 Scene",    "performers": [      {        "email": "performer@example.com"      }    ],    "uploaderAttestation": {      "ip": "203.0.113.7",      "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",      "clickedAt": "2026-04-24T18:00:00Z",      "attestationText": "I coordinated this scene, all performers were 18+ and consented on set"    },    "callbackUrl": "https://your-platform.com/webhooks/ez2257"  }'

{
  "sceneId": "cmd5r9a4t0001qz8hb6k2m3xd",
  "status": "pending_signatures",
  "performers": [
    {
      "email": "performer@example.com",
      "status": "pending_consent"
    }
  ],
  "fees": {
    "sceneFeeCents": 500,
    "onboardingFeeCents": 2500,
    "totalCents": 3000,
    "charged": true,
    "stripeChargeId": "pi_3NabcDEfghIJklmn",
    "billedTo": "uploader_card",
    "chargeError": null
  },
  "expiresAt": "2026-05-08T18:00:00Z"
}

{
  "error": "email, externalUserId, and callbackUrl are required",
  "code": "missing_parameter",
  "field": "contentType"
}

{
  "error": "email, externalUserId, and callbackUrl are required",
  "code": "missing_parameter",
  "field": "contentType"
}

{
  "error": "email, externalUserId, and callbackUrl are required",
  "code": "missing_parameter",
  "field": "contentType"
}

{
  "error": "Too many requests. Please slow down.",
  "retryAfter": 14,
  "limit": 60,
  "remaining": 0,
  "reset": 1714000060000
}

{
  "error": "email, externalUserId, and callbackUrl are required",
  "code": "missing_parameter",
  "field": "contentType"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`