# Confirm Professional Roster Addition

Source: https://recoupable.dev/docs/api-reference/organizations/professionals-confirm

Confirm professional roster addition

## POST /api/organizations/professionals

Full OpenAPI specification: https://recoupable.dev/docs/spec/accounts.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "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"
    }
  ],
  "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).",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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](/docs/quickstart#api-keys)."
      }
    }
  }
}
```