Terms Setup API Endpoints

PreviousNext

Complete API reference for Terms Setup endpoints

API Overview

The Terms Setup API provides four endpoints for managing IP licensing terms. All endpoints require authentication and return standardized JSON responses.

Base Path: /api/terms-setup

Authentication

All endpoints require authentication via session cookie. The API validates the session and extracts user information including roles for authorization checks.

Response Format

All endpoints return responses in this format:

Success Response:

{
  "status": "success",
  "data": { /* endpoint-specific data */ }
}

Error Response:

{
  "status": "error",
  "error": "Error message describing what went wrong"
}

Endpoints

1. Get or Create IP Terms

Endpoint: POST /api/terms-setup/getOrCreateIpTerms

Purpose: Retrieves existing IP terms for a specific type, or generates default terms if none exist. This endpoint has a side-effect of creating records when they don't exist, hence the explicit naming and POST method.

Request Body:

  • ipTermType (required): One of "VoiceOver", "Likeness", "Image"
  • accountId (optional): Target account ID (requires admin role if different from authenticated user's account)

HTTP Status Codes:

  • 200 OK - Success, existing term retrieved
  • 201 Created - Success, new term generated
  • 400 Bad Request - Invalid ipTermType or validation error
  • 401 Unauthorized - Not authenticated
  • 403 Forbidden - Not authorized to access target account (admin check failed)
  • 500 Internal Server Error - Server error

Response Data:

  • ipTerms - Raw database record
  • sellerData.sellerName - Seller name from account display name
  • fmtIpTerms - Formatted terms with legal text:
    • id - Term ID
    • ipTermType - Term type
    • ipApprove - Approval status
    • legalText:
      • shortTerms - Brief description with seller name
      • bullets - Array of formatted bullet points
      • longTerms - Full legal text
  • priceUSDollar - Compensation value as number (null if not set)
  • accountData - Full account data for client-side use

Behavior:

  1. Authenticates user
  2. If accountId provided, verifies user has "admin" role
  3. Validates ipTermType is a valid enum value
  4. Queries for existing term with matching accountId and ipTermType (excluding soft-deleted)
  5. If found: formats and returns existing term (200 OK)
  6. If not found: generates default terms and creates record (201 Created)
  7. Returns formatted result with account data

Example Request:

{
  "ipTermType": "VoiceOver"
}

Example Response (201 Created):

{
  "status": "success",
  "data": {
    "ipTerms": {
      "id": "abc123",
      "accountId": "acc456",
      "ipTermType": "VoiceOver",
      "compensationType": null,
      "compensationValue": null,
      "ipApprove": false,
      "termsVersion": 1,
      "createdBy": "user789",
      "createdAt": "2026-02-12T10:00:00Z"
    },
    "sellerData": {
      "sellerName": "John Doe"
    },
    "fmtIpTerms": {
      "id": "abc123",
      "ipTermType": "VoiceOver",
      "ipApprove": false,
      "legalText": {
        "shortTerms": "John Doe's VoiceOver licensing terms...",
        "bullets": [],
        "longTerms": "Full legal text..."
      }
    },
    "priceUSDollar": null,
    "accountData": { /* account object */ }
  }
}

2. Approve IP Terms

Endpoint: POST /api/terms-setup/approveIpTerms

Purpose: Updates IP terms with new data and marks them as approved.

Request Body:

  • ipTermsId (required): ID of the IpTerms record to update
  • accountId (optional): Target account ID (requires admin role if different from authenticated user's account)
  • ipTerms (required): Partial update data:
    • compensationType (optional): Must be valid value from compensationTypes enum
    • compensationValue (optional): Must be non-negative number if provided
    • approvalType (optional): Must be valid value from approvalTypes enum
    • permittedUsage (optional): Free-text field describing permitted usage
    • additionalRestrictions (optional): Free-text field for additional restrictions
    • additionalShareData (optional): Free-text field for additional data sharing requirements

HTTP Status Codes:

  • 200 OK - Success, term updated and approved
  • 400 Bad Request - Invalid input data or validation error
  • 401 Unauthorized - Not authenticated
  • 403 Forbidden - Not authorized to update target account (admin check failed or ownership mismatch)
  • 404 Not Found - IP term not found
  • 500 Internal Server Error - Server error

Response Data: Same structure as Get-or-Create response (FormattedIpTermsResult), but without accountData.

Behavior:

  1. Authenticates user
  2. If accountId provided, verifies user has "admin" role
  3. Validates input:
    • ipTermsId is required and valid string
    • compensationType is valid enum value (if provided)
    • compensationValue is non-negative number (if provided)
    • approvalType is valid enum value (if provided)
  4. Queries term by id (excluding soft-deleted)
  5. Verifies ownership: Checks accountId matches authenticated user's account or user has "admin" role
  6. Updates term record:
    • Merges ipTerms update data
    • Sets ipApprove: true
    • Sets updatedBy to authenticated user ID
    • Sets updatedAt to current timestamp
  7. Logs audit event
  8. Formats and returns updated terms

Example Request:

{
  "ipTermsId": "abc123",
  "ipTerms": {
    "compensationType": "ONE_TIME_FEE_PER_IMAGE",
    "compensationValue": 50.00,
    "approvalType": "APPROVAL_BY_USER",
    "permittedUsage": "Commercial use in marketing materials",
    "additionalRestrictions": "No use in adult content"
  }
}

Example Response:

{
  "status": "success",
  "data": {
    "ipTerms": {
      "id": "abc123",
      "accountId": "acc456",
      "ipTermType": "Image",
      "ipApprove": true,
      "compensationType": "ONE_TIME_FEE_PER_IMAGE",
      "compensationValue": "50.00",
      "termsVersion": 1,
      "updatedBy": "user789",
      "updatedAt": "2026-02-12T11:00:00Z"
    },
    "fmtIpTerms": { /* formatted terms */ },
    "priceUSDollar": 50.00
  }
}

3. Delete IP Terms (Soft Delete)

Endpoint: DELETE /api/terms-setup/deleteIpTerms

Purpose: Soft-deletes an IP terms record by setting deletedAt timestamp. Records are not physically deleted to maintain audit trail.

Query Parameters:

  • ipTermsId (required): ID of the IpTerms record to soft-delete
  • accountId (optional): Target account ID (requires admin role if different from authenticated user's account)

HTTP Status Codes:

  • 200 OK - Success, term soft-deleted
  • 400 Bad Request - Invalid ipTermsId
  • 401 Unauthorized - Not authenticated
  • 403 Forbidden - Not authorized to delete target account (admin check failed or ownership mismatch)
  • 404 Not Found - IP term not found
  • 500 Internal Server Error - Server error

Response Data: The soft-deleted record with deletedAt set.

Behavior:

  1. Authenticates user
  2. If accountId provided, verifies user has "admin" role
  3. Validates ipTermsId is required and valid string
  4. Queries term by id (excluding already soft-deleted)
  5. Verifies ownership: Checks accountId matches authenticated user's account or user has "admin" role
  6. Soft-deletes the record:
    • Sets deletedAt to current timestamp
    • Sets updatedBy to authenticated user ID
    • Sets updatedAt to current timestamp
    • Does NOT physically delete the record
  7. Logs audit event
  8. Returns the soft-deleted record

Example Request:

DELETE /api/terms-setup/deleteIpTerms?ipTermsId=abc123

Example Response:

{
  "status": "success",
  "data": {
    "id": "abc123",
    "accountId": "acc456",
    "ipTermType": "VoiceOver",
    "deletedAt": "2026-02-12T12:00:00Z",
    "updatedBy": "user789",
    "updatedAt": "2026-02-12T12:00:00Z"
  }
}

4. List All IP Terms

Endpoint: GET /api/terms-setup/listIpTerms

Purpose: Retrieves all IP terms for an account in a single request, excluding soft-deleted records.

Query Parameters:

  • accountId (optional): Target account ID (requires admin role if different from authenticated user's account)

HTTP Status Codes:

  • 200 OK - Success, terms retrieved
  • 401 Unauthorized - Not authenticated
  • 403 Forbidden - Not authorized to access target account (admin check failed)
  • 500 Internal Server Error - Server error

Response Data:

  • terms - Array of FormattedIpTermsResult objects (one per term type)

Behavior:

  1. Authenticates user
  2. If accountId provided, verifies user has "admin" role
  3. Determines target account: Uses provided accountId or authenticated user's account
  4. Queries all terms for the account (excluding soft-deleted)
  5. Formats each term using formatIpTerms()
  6. Returns array of formatted terms

Example Request:

GET /api/terms-setup/listIpTerms

Example Response:

{
  "status": "success",
  "data": {
    "terms": [
      { /* VoiceOver term */ },
      { /* Image term */ },
      { /* Likeness term */ }
    ]
  }
}

Enum Values

IP Term Types

  • "VoiceOver" - Voice recordings and audio content
  • "Likeness" - Person's likeness or appearance
  • "Image" - Images and photographs

Compensation Types

  • "ONE_TIME_FEE_PER_MINUTE" - One-time fee per minute of audio
  • "ONE_TIME_FEE_PER_SECOND" - One-time fee per second of audio
  • "ONE_TIME_FEE_PER_IMAGE" - One-time fee per image
  • "PERCENTAGE_OF_NET_REVENUES" - Percentage of net revenues
  • "PAYMENT_PER_1000_VIEWS" - Payment per 1000 views
  • "MAKE_ME_AN_OFFER" - Custom offer

Approval Types

  • "NO_APPROVAL_NEEDED" - Automatic usage without approval
  • "APPROVAL_BY_USER" - Seller must approve each use
  • "APPROVAL_BY_AGENT" - Designated agent approves uses
  • "APPROVAL_BY_AI" - Automated approval based on criteria

Error Messages

Common error messages:

  • "IP term not found" - Term doesn't exist (404)
  • "Unauthorized: This term does not belong to you" - Ownership mismatch (403)
  • "Permission denied" - Cannot edit target account (403)
  • "Invalid IP term type" - Unsupported term type (400)
  • "ipTermsId is required" - Missing required parameter (400)
  • "Invalid compensation value" - Negative or invalid number (400)
  • "Invalid enum value" - Invalid compensationType or approvalType (400)

Admin Access

Users with the "admin" role can manage terms for any account:

  1. Provide accountId parameter in request
  2. System verifies user has "admin" role
  3. If verified, operation proceeds on target account
  4. If not admin, returns 403 Forbidden

This enables support workflows and administrative management of terms across accounts.