Easy2257 Talent API

openapi: 3.2.0
info:
  title: Easy2257 Partner Talent API
  version: '2026-07-27'
  description: 'The Easy2257 Partner API lets your platform outsource 18 U.S.C. § 2257 compliance in a single integration: performer ID verification, per-depiction content logging, and 7-year record retention, with Easy2257 named Custodian of Records. No endpoint in this API returns a performer''s legal name, date of birth, government ID image, or Easy2257 user id. A platform integrating it never touches a government ID, so it cannot leak one. There is no sandbox: only `ez_live_` keys are accepted, and every call writes a production record.'
  contact:
    name: Easy2257 Developer Support
    email: api@easy2257.com
    url: https://docs.easy2257.com
servers:
- url: https://easy2257.com
  description: Production, and the only environment. There is no sandbox host.
tags:
- name: Talent
  description: Check whether a creator you provisioned is verified.
paths:
  /api/v1/talent/check:
    post:
      summary: Check performer verification status
      description: 'Answers one question about one of your own creators: are they verified right now. Scoped to accounts you provisioned, so it returns `found: false` for every address you did not, including creators verified through another platform. It cannot be used to discover whether an arbitrary email has an Easy2257 account, and it never returns a name, a date of birth, or an ID.'
      tags:
      - Talent
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TalentCheckBody'
      responses:
        '200':
          description: 'Lookup result. A miss is a 200 with `found: false`, not a 404.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TalentCheckResponse'
        '400':
          description: '`email` missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'No `Authorization: Bearer` header, or a key that is unknown, revoked, or expired. The body carries only `error`, never a `code`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Rejected before the handler: a test-mode key (`TEST_MODE_UNAVAILABLE`) or a partner account that is not ACTIVE. Never used for cross-partner access, which returns 404.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limit exceeded: 300 requests per 60 seconds per API key, shared across all `/api/v1` endpoints (requests without a `Bearer` key fall back to 60 per 60 seconds per client IP, and a per-address flood ceiling of 1200 per 60 seconds also applies). Honor `Retry-After`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Server error. Retry with exponential backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiV1TalentCheck
      x-operation-id-source: derived
components:
  schemas:
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Too many requests. Please slow down.
        retryAfter:
          type: integer
          description: Seconds until the window frees up. Mirrors the `Retry-After` header.
          example: 14
        limit:
          type: integer
          description: Requests allowed per window.
          example: 60
        remaining:
          type: integer
          example: 0
        reset:
          type: integer
          description: Epoch milliseconds at which the sliding window releases the oldest request.
          example: 1714000060000
      required:
      - error
      - limit
      - remaining
      - reset
    TalentCheckBody:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Matched case-insensitively against the exact address you provisioned. Plus-tags and dots are not folded here.
          example: creator@example.com
      required:
      - email
    TalentCheckResponse:
      type: object
      properties:
        found:
          type: boolean
          description: Whether this address matches an account you provisioned. Always false for anyone you did not provision, including creators verified through another platform.
        verified:
          type: boolean
          description: True only when that account's status is `active`.
        lastVerifiedAt:
          type:
          - string
          - 'null'
          description: 'Date of the most recent approved verification as `YYYY-MM-DD`, or null. Date only: no time, and no verification detail.'
          example: '2026-04-01'
      required:
      - found
      - verified
      - lastVerifiedAt
    Error:
      type: object
      properties:
        error:
          type: string
          description: 'Human-readable message. Switch on HTTP status and on `code`, never on this string: it is not part of the API contract.'
          example: email, externalUserId, and callbackUrl are required
        code:
          type: string
          description: Machine-readable error code. Present on the test-key rejection (`TEST_MODE_UNAVAILABLE`), consent conflicts, and most collab-scene and upload-session validation errors. Never present on `401` authentication rejections, and absent on the inactive-partner `403` and on some older solo-account validation errors, which is why status is the primary signal.
          example: missing_parameter
        field:
          type: string
          description: The offending request field. Present on collab-scene and upload-session validation errors.
          example: contentType
      required:
      - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: '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.'