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

# Record an Executed Producer Agreement

> Record a signed producer agreement for an agency you appoint

Records a signed PDF as the agency's executed producer agreement. The result is the same as **Upload Executed Agreement** in the Turris app: the agreement shows in the agency's Producer agreement section, the agency's contract onboarding step is complete, and [Producer Agreement Executed](https://docs.turrisfi.com/guides/webhooks/producer-agreement-executed.md) is sent to your webhook and to your team.

Send the PDF as `multipart/form-data` in the `file` part, 25 MB at most. Signature dates and the effective date are read from the PDF shortly after the call.

If the agency has no contract yet (for example an agency you added rather than invited), Turris creates it from your default active contract template, or without a template if you have no single default.

## When nothing is recorded

Both of these answer `409` and write nothing:

* **`contract_already_signed`**: the agency's agreement is already executed. If you are retrying a call that may have succeeded, treat this as already recorded.
* **`online_signing_in_progress`**: an online (DocuSign) signing is attached to the agreement. Send `cancelOnlineSigning=true` to cancel it and record this PDF in its place. Cancelling cannot be undone.

## Uploading through Upload a Document

A Producer Agreement sent to [Upload a Document](https://docs.turrisfi.com/api-reference/v2/file-documents/upload-document.md) is stored, but it does not execute the agreement. Use this endpoint instead.


## OpenAPI

````yaml openapi/v2.json POST /v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/executed-producer-agreement
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security:
  - bearer: []
  - restricted-access-token: []
tags:
  - name: auth
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: downstream/actions-required
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/appointments
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/carriers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/compliance-configs
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/contacts
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/corporate-registrations
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/documents
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/entities
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-overview
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-requests
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/licenses
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/markets
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/producers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-filings
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-states
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: heartbeat
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: upstream/agents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/agents-license-compliance
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/appointment-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/carriers
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/compliance-data-subscriptions
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contract-container-templates
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/diligent-effort-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/downstream-entity-associations
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/file-documents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/market-contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/npn-lookup
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/policies
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/products
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-filings
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-states
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/termination-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId}/executed-producer-agreement:
    post:
      tags:
        - upstream/downstream-entity-associations
      summary: Record an Executed Producer Agreement
      description: >-
        Records a signed PDF as this agency's executed producer agreement, as
        Upload Executed Agreement does in the app: the agreement shows in the
        agency's Producer agreement section, the agency's contract onboarding
        step is completed, and PRODUCER_AGREEMENT_EXECUTED is sent. Signature
        and effective dates are read from the PDF shortly after the call.
      operationId: >-
        AssociatedDownstreamEntitiesV2Controller_recordExecutedProducerAgreement_v2
      parameters:
        - name: downstreamEntityAssociationId
          required: true
          in: path
          description: Downstream entity association ID
          schema:
            example: 507f1f77bcf86cd799439011
            type: string
        - name: idempotency-key
          in: header
          description: UUID to ensure idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-idempotency-key
          in: header
          description: Alternative UUID header for idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              allOf:
                - $ref: '#/components/schemas/RecordExecutedProducerAgreementDto'
                - type: object
                  required:
                    - file
                  properties:
                    file:
                      type: string
                      format: binary
                      description: The signed producer agreement. PDF only, 25 MB maximum.
      responses:
        '201':
          description: Executed producer agreement recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: >-
                      #/components/schemas/RecordedExecutedProducerAgreementResponse
                  requestId:
                    type: string
                    description: Unique request identifier
                    example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-11-12T20:49:03.293Z'
                required:
                  - data
                  - requestId
                  - timestamp
        '400':
          description: >-
            No file, a file that is not a PDF, an invalid association id, or an
            invalid cancelOnlineSigning
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Returned with `errorType` `invalid_organization_category` when your
            credential's organization category does not match the one this
            endpoint serves; `details` names the expected and actual category.
            This endpoint can return 403 for other reasons too, so branch on
            `errorType`; the Error Handling guide lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Downstream entity association not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '409':
          description: >-
            The agreement is already executed (contract_already_signed), or an
            online signing is attached and cancelOnlineSigning is not true
            (online_signing_in_progress). Nothing was recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '413':
          description: The file is larger than 25 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            More than 120 requests to this endpoint in 60 seconds from your
            organization. Also returned when this credential passes the API-wide
            limit of 1000 requests per 10 seconds, counted across every
            endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent when a rate limit refused
                the request.
              schema:
                type: integer
components:
  schemas:
    RecordExecutedProducerAgreementDto:
      type: object
      properties:
        cancelOnlineSigning:
          type: boolean
          description: >-
            Set to true to cancel an online (DocuSign) signing attached to the
            agreement and record this one in its place. Without it, an attached
            signing returns 409 online_signing_in_progress and nothing is
            recorded. Has no effect when no signing is attached.
          default: false
    RecordedExecutedProducerAgreementResponse:
      type: object
      properties:
        signedFileDocumentId:
          type: string
          description: >-
            The document holding the signed PDF. Fetch it with Get a Download
            URL for a Document. Its signature and effective dates are filled in
            by extraction shortly after this call.
        contractContainerInstanceId:
          type: string
          description: >-
            The agency's contract record. The PRODUCER_AGREEMENT_EXECUTED
            webhook carries the same value as contractContainerInstanceId.
      required:
        - signedFileDocumentId
        - contractContainerInstanceId
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: >-
            Machine-readable error classification. Branch on this rather than on
            `errorMessage`, which is prose and may change. Authentication
            failures returned by our identity provider are forwarded verbatim,
            so a 401 can carry a code outside this list; treat an unrecognised
            value as a generic failure of its HTTP status.
          enum:
            - conflict
            - contact_not_authorized
            - contract_already_signed
            - document_exceeds_page_limit
            - downstream_entity_member_exists
            - duplicate_external_id_error
            - duplicate_member_email
            - duplicate_producer_code_error
            - forbidden
            - gateway_timeout
            - inactive_email
            - internal_server_error
            - invalid_email
            - invalid_email_for_invites
            - invalid_organization_category
            - invalid_organization_slug
            - invalid_phone_number
            - invalid_token
            - invite_limit_reached
            - jwt_invalid
            - m2m_client_not_found
            - not_found
            - online_signing_in_progress
            - organization_already_exists
            - organization_slug_already_used
            - payment_required
            - producer_agreement_required
            - product_feature_subscription_required
            - service_unavailable
            - session_authorization_error
            - some_custom_error_string
            - throttled
            - too_many_requests
            - unauthorized
            - unauthorized_client
            - unexpected_400_stytch_error
            - unexpected_403_stytch_error
            - unexpected_404_stytch_error
            - unexpected_error
            - unexpected_stytch_error
            - unprocessable_entity
            - validation_error
          example: validation_error
        errorMessage:
          description: Array of error messages
          type: array
          items:
            type: string
        timestamp:
          type: string
          description: ISO timestamp when the error occurred
        details:
          type: object
          description: Additional error context
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    restricted-access-token:
      type: apiKey
      in: header
      name: x-restricted-access-token
      description: >-
        Alternative authentication: Restricted access token (if not using Bearer
        token)

````

## Related topics

- [Changelog](https://docs.turrisfi.com/changelog.md)
- [Upload a Document](https://docs.turrisfi.com/api-reference/v2/file-documents/upload-document.md)
- [Producer Agreement Executed](https://docs.turrisfi.com/guides/webhooks/producer-agreement-executed.md)


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