> ## 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. # Update Association > Set or clear the external ID and producer code on a downstream entity association Updates the two identifiers you own on an association: `externalId` and `producerCode`. Send a non-empty string to set a field, `null` to clear it, and leave a key out to keep its stored value. At least one of the two keys must be present. Both values are unique across your associations. Sending a value another of your associations already carries returns `409` with `errorType` `duplicate_external_id_error` or `duplicate_producer_code_error`. Sending an association's own current value back is not a conflict. The usual reason to call this is an integration that keyed an association to the wrong record in your system and needs to move its external ID. The response is the full association, identical in shape to [Get Association](/api-reference/v2/downstream-entity-associations/get-association). ## OpenAPI ````yaml openapi/v2.json PATCH /v2/upstream/downstream-entity-associations/{downstreamEntityAssociationId} 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/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: 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/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/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}: patch: tags: - upstream/downstream-entity-associations operationId: >- AssociatedDownstreamEntitiesV2Controller_updateDownstreamEntityAssociation_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: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateDownstreamEntityAssociationDto' - type: object minProperties: 1 responses: '200': description: Updated downstream entity association content: application/json: schema: type: object properties: data: $ref: >- #/components/schemas/DownstreamEntityAssociationWithHierarchyResponseDto 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: >- Invalid request body, or neither externalId nor producerCode was supplied 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 externalId or producerCode is already used by another of your downstream entity associations content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: UpdateDownstreamEntityAssociationDto: type: object properties: externalId: type: string description: >- Your own identifier for this association, for example the record key in your producer management system. Pass a non-empty string to set it, or null to clear it. An empty string is rejected. Must be unique across your associations. Leave the key out to keep the stored value. example: EXT-12345 nullable: true minLength: 1 producerCode: type: string description: >- Producer code you assign to this downstream entity location. Pass a non-empty string to set it, or null to clear it. An empty string is rejected. Must be unique across your associations. Leave the key out to keep the stored value. example: PROD-001 nullable: true minLength: 1 DownstreamEntityAssociationWithHierarchyResponseDto: type: object properties: _id: type: string description: Association ID producerCode: type: string description: Producer code externalId: type: string description: External ID branchName: type: string description: Branch or office name for this association creationPath: type: string description: >- How this association was created: invitation, addition, bulk-upload, market, or hubspot sync. Immutable once set. downstreamEntity: description: Downstream entity details allOf: - $ref: '#/components/schemas/PopulatedDownstreamEntityResponse' niprDataSubscription: description: NIPR data subscription for this association allOf: - $ref: '#/components/schemas/ComplianceDataSubscriptionResponse' path: type: string description: >- Materialized ancestor chain, "/rootId/parentId/currentId". Segments are association ids, so each one can be looked up through this same endpoint. A top-level agency is "/ownId". Snapshot: moving an agency to a different parent rewrites it. In the rare case where an association has no stored path, this is synthesized as "/ownId" so the field is always present. level: type: number description: Depth in the hierarchy. 0 is a top-level agency. parentAssociationId: type: string description: >- Immediate parent association id. Null for a top-level agency, never absent. nullable: true ultimateParentAssociationId: type: string description: >- First segment of path. A top-level agency is its own ultimate parent. ultimateParentAgreementExecuted: type: boolean description: >- Whether the ultimate parent has an executed producer agreement. Always refers to the ROOT of the chain, never to the nearest ancestor that happens to have signed; at depth two those coincide. Snapshot as of this response. required: - _id - downstreamEntity - niprDataSubscription - path - level - parentAssociationId - ultimateParentAssociationId - ultimateParentAgreementExecuted 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 - 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 - 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 PopulatedDownstreamEntityResponse: type: object properties: _id: type: string description: Downstream entity ID isNpnRequired: type: boolean description: Whether NPN is required for this downstream entity legalName: type: string description: Legal name of the downstream entity category: type: string description: Category of the downstream entity npn: type: string description: National Producer Number ein: type: string description: Employer Identification Number required: - _id - isNpnRequired - legalName - category - npn - ein ComplianceDataSubscriptionResponse: type: object properties: dataOwnerId: type: string description: Data owner ID dataOwnerModel: type: string description: Data owner model type entityModel: type: string description: Entity model type npn: type: string description: National Producer Number nullable: true entityInfo: description: NIPR entity info details allOf: - $ref: '#/components/schemas/NiprEntityInfoResponse' lastSynchronizationDate: format: date-time type: string description: Last synchronization date pdbAlertsSubscriptionStatus: type: string description: PDB Alerts subscription status pdbAlertsPausedAt: format: date-time type: string description: Date when PDB Alerts was paused required: - dataOwnerId - dataOwnerModel - entityModel - entityInfo NiprEntityInfoResponse: type: object properties: status: type: string description: Status of the NIPR data subscription jobId: type: string description: Job ID for the NIPR entity info request message: type: string description: Message associated with the status rawEntityInfoId: type: string description: Raw entity info document ID required: - status 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](/changelog.md) - [Update Policy](/api-reference/v2/policies/update-policy.md) - [Agency Updated](/guides/webhooks/downstream-entity-updated.md)