> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm Professional Roster Addition

> Requires explicit operator identity confirmation and organization roster intent. Use new only after confirming a distinct professional, including resolving same-name candidates; never infer identity from a name. Use existing with a professional_id from this organization to add roles without renaming. Both songwriter and producer can belong to one record. This operation creates no login account, shared canonical identity, catalog rights, enrichment job, or cross-workspace context. Research/name intake alone never calls this operation. Membership is rechecked before idempotency replay. Legacy MCP equivalent (API key or Privy token): confirm_professional_roster. Not exposed through delegated OAuth MCP. Returns the original saved response on retry, including its created flag and original status (201 for a new record, 200 for an existing record).



## OpenAPI

````yaml api-reference/openapi/accounts.json POST /api/organizations/professionals
openapi: 3.1.0
info:
  title: Recoup API - Accounts
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/organizations/professionals:
    post:
      summary: Confirm professional roster addition
      description: >-
        Requires explicit operator identity confirmation and organization roster
        intent. Use new only after confirming a distinct professional, including
        resolving same-name candidates; never infer identity from a name. Use
        existing with a professional_id from this organization to add roles
        without renaming. Both songwriter and producer can belong to one record.
        This operation creates no login account, shared canonical identity,
        catalog rights, enrichment job, or cross-workspace context.
        Research/name intake alone never calls this operation. Membership is
        rechecked before idempotency replay. Legacy MCP equivalent (API key or
        Privy token): confirm_professional_roster. Not exposed through delegated
        OAuth MCP. Returns the original saved response on retry, including its
        created flag and original status (201 for a new record, 200 for an
        existing record).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                organization_id:
                  type: string
                  format: uuid
                idempotency_key:
                  type: string
                  format: uuid
                  description: >-
                    Generate once per deliberate operation. Persist and reuse
                    after a timeout or lost response. Scoped to the organization
                    and actor. Different input with the same key is rejected.
                mode:
                  type: string
                  enum:
                    - new
                    - existing
                name:
                  type: string
                  minLength: 2
                  maxLength: 200
                professional_id:
                  type: string
                  format: uuid
                roles:
                  type: array
                  minItems: 1
                  maxItems: 2
                  items:
                    type: string
                    enum:
                      - songwriter
                      - producer
                confirmed:
                  type: boolean
                  enum:
                    - true
                roster_intent:
                  type: string
                  enum:
                    - add
              required:
                - organization_id
                - idempotency_key
                - mode
                - roles
                - confirmed
                - roster_intent
              oneOf:
                - properties:
                    mode:
                      enum:
                        - new
                  required:
                    - name
                  not:
                    required:
                      - professional_id
                - properties:
                    mode:
                      enum:
                        - existing
                  required:
                    - professional_id
                  not:
                    required:
                      - name
      responses:
        '200':
          description: >-
            Existing professional roles saved, or replayed existing-record
            operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - professional
                  - created
                properties:
                  professional:
                    $ref: '#/components/schemas/OrganizationProfessional'
                  created:
                    type: boolean
        '201':
          description: New professional saved, or replayed new-record operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - professional
                  - created
                properties:
                  professional:
                    $ref: '#/components/schemas/OrganizationProfessional'
                  created:
                    type: boolean
        '400':
          description: Invalid or unconfirmed request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '403':
          description: >-
            Organization access denied, revoked, or record outside this
            organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '409':
          description: Request key already used for different input or actor
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '503':
          description: >-
            Unavailable storage or unconfirmed response; retry with the same key
            and input
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    OrganizationProfessional:
      type: object
      required:
        - id
        - organization_id
        - name
        - roles
        - confirmed_by
        - confirmation_basis
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        organization_id:
          type: string
          format: uuid
        name:
          type: string
        roles:
          type: array
          items:
            type: string
            enum:
              - songwriter
              - producer
        confirmed_by:
          type: string
          format: uuid
        confirmation_basis:
          type: string
          enum:
            - operator_confirmed
          description: >-
            Operator assertion for this organization; not a globally verified
            person identity.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.