Portfolio Intake

Portfolio intake is the first governed workflow for artists texting portfolio work, flash, references, and ideas to a managed number. The product goal is personal for artists and strict for the platform: inbound media can be staged, classified, reviewed, and promoted into approved portfolio storage, but it cannot jump straight from a text message into public distribution.

Communications API credentials can be ready before SMS/MMS launch is ready. A2P approval remains required before treating SMS/MMS intake as production-ready.

Review-gated surface: this workflow can stage evidence and prepare review records, but it cannot publish, promote, or write approved portfolio data without TattooAPI policy checks and human approval.

Private workers cannot write directly to approved portfolio storage, mutate canonical runtime tables, activate public surfaces, change identity mappings, or publish inbound media. They return classification and review evidence to TattooAPI.

Partner API Staging

Approved services use a partner API key with portfolio_intake:stage. Add artists:read only when the integration also needs authorized artist profile reads.

curl -X POST "https://api.tattooapi.com/api/private/portfolio-intake/v1/submissions" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "opaque-message-id:opaque-attachment-id",
    "tenantId": "studio_canonical_id",
    "studioCanonicalId": "studio_canonical_id",
    "artistCanonicalId": "artist_canonical_id",
    "source": "permanent_imessage",
    "sourceMessageId": "opaque-message-id",
    "fileName": "portfolio.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 1048576,
    "rightsPosture": "review_required",
    "consentPosture": "review_required"
  }'

TattooAPI returns a five-minute private signed PUT URL and an awaiting_upload submission. Upload the exact media bytes using the returned Content-Type header. By default, the API key mapping must already include the requested studio or artist canonical ID; cross-tenant submissions return 403. An explicitly approved service mapping may carry the internal portfolio_intake:stage_cross_tenant capability for governed identity resolution and staging across approved tenants. This capability belongs to TattooAPI’s TattooAPI actor mapping, not to the partner key, and never grants approval or publication authority. While a submission remains awaiting_upload, legitimate idempotent replay returns the existing submission and a new signed URL for that submission’s persisted object key. TattooAPI never re-signs a PUT after completion. Reusing an idempotency key with a different semantic envelope fails closed instead of changing the staged pointer.

Complete the Upload

After the PUT succeeds, call the bodyless completion route with the same partner API key and portfolio_intake:stage permission:

curl -X POST \
  "https://api.tattooapi.com/api/private/portfolio-intake/v1/submissions/$SUBMISSION_ID/upload-complete" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"

This route accepts X-API-Key only. Bearer-only requests and requests that mix Authorization with X-API-Key are rejected before submission lookup or storage verification. TattooAPI reads the private uploaded file, checks its image signature and stored MIME metadata, compares its actual byte count with the original submission, computes and persists a server-side SHA-256 digest, and requires an opaque ETag. Only image/jpeg, image/png, image/webp, and image/heic are accepted. image/heif is not supported. The first valid completion atomically transitions awaiting_upload to awaiting_review and returns action: "completed". A later replay returns HTTP 200 with action: "already_completed" from the persisted verification evidence. Missing objects, size or MIME mismatch, integrity conflict, or any other intake state leave the submission unadvanced. Completion is a staging transition only. It cannot publish or change the artist identity. The submission remains review_required. A different operator identity with portfolio_intake:review must approve it through:

POST /api/private/portfolio-intake/v1/submissions/{submissionId}/approve

Approval is available only after upload completion has produced awaiting_review. It requires non-review rights and consent posture, verifies that the private uploaded file exists, uploads the image to the approved portfolio storage, and creates a private tattooPortfolioAsset draft. It does not activate public distribution or publication. The submitting service can poll its own bounded status through:

GET /api/private/portfolio-intake/v1/submissions/{submissionId}

The response can move through awaiting_upload, awaiting_review, promotion_failed, and promoted_to_sanity. Even promoted_to_sanity does not make the asset public; public reads require a separate governed runtime and distribution promotion.

Identity Evidence, Not KYC

TattooAPI v0 identity evidence helps route portfolio media to review. It is not legal KYC and does not claim government identity verification.

Status	Meaning	What happens next
`unmatched`	No reliable contact, phone hash, or profile mapping was found.	Keep the item in review.
`phone_matched`	A normalized phone hash or contact record matched known TattooAPI evidence.	Review can use the match as evidence, not final proof.
`review_required`	Evidence is partial, conflicting, or below confidence threshold.	Operator review is required before any approved write.
`verified_by_operator`	A human operator approved the identity evidence for this workflow.	The item can proceed to approved workflow steps if all other gates pass.

Do not label a record kyc_verified unless a future legal identity provider is explicitly added and approved.

Publication

Submissions remain private until review and separate distribution approval. Use the Portfolio Intake Workflow and each endpoint reference to handle state transitions.

Start Here

Integration Guides

Portfolio Intake

Portfolio Intake

Partner API Staging

Complete the Upload

Identity Evidence, Not KYC

Publication

​Portfolio Intake

​Partner API Staging

​Complete the Upload

​Identity Evidence, Not KYC

​Publication

Portfolio Intake

Partner API Staging

Complete the Upload

Identity Evidence, Not KYC

Publication