> ## 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. # Add a Producer > Create a producer and associate them with your entities Creates a producer and associates them with one or more of your entities. Every id in `entityIds` must be inside your subtree; one that is not returns **404** and nothing is written. ## NPN behaviour * **With an `npn`**, an existing producer holding that NPN is reused and associated with your entities rather than duplicated. This is what you want: NPN is the producer's identity across the industry. * **Without an `npn`**, a new producer record is always created. There is no name matching, deliberately — two people can share a name, and merging them silently would be worse than creating a second record you can reconcile. ## Sensitive fields `ssn` is optional, encrypted at rest, and never returned by any endpoint on this API. `dateOfBirth` is stored and likewise never returned. ## Re-running this request Associating a producer with an entity they are already on returns **409**. Use [Assign a Producer to Entities](/api-reference/v2/downstream/producers/assign-producer-entities) to add entities to an existing producer — that one skips entities already covered instead of failing. Send an `Idempotency-Key` header. See [Idempotency](/guides/idempotency). ## OpenAPI ````yaml openapi/v2.json POST /v2/downstream/producers 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: [] tags: [] paths: /v2/downstream/producers: post: tags: - downstream/producers summary: Add a producer description: >- Creates a producer and associates them with the entities you name, returning them in the same shape List Producers uses. Supplying an NPN reuses an existing producer who already has it rather than duplicating the person; omitting one always creates a new producer, because there is nothing to match on. Every entity id must be one of yours, and one that is not fails the whole request. A producer already associated with one of the entities returns 409 — use Assign Producer Entities to add them to more. operationId: ProducersController_addProducer_v2 parameters: - 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: $ref: '#/components/schemas/AddProducerDto' responses: '201': description: The producer that was created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DownstreamProducerResponse' 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 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: Your organization is not entitled to the public API content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: One of the entity ids is not in your organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '409': description: >- The producer is already associated with one of the entities you named content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: AddProducerDto: type: object properties: firstName: type: string description: Given name example: Jon middleName: type: string description: Middle name example: R lastName: type: string description: Surname example: Doe npn: type: string description: >- National Producer Number. When supplied, an existing producer with this NPN is reused rather than duplicated. When omitted, a new producer is always created. example: '7654321' ssn: type: string description: >- Social Security Number, with or without hyphens. Encrypted at rest and never returned by any endpoint: reads expose the last four digits only. Required by NIPR for licence renewal submissions, so a producer added without one cannot be submitted for renewal until it is supplied. example: 123-45-6789 dateOfBirth: type: string description: >- ISO 8601 date of birth. Required by NIPR alongside the SSN for renewal submissions. example: '1985-04-12' email: type: string description: Contact email for this producer at your agency example: example@test.com tel: type: string description: Contact phone number example: '+12155550100' position: type: string description: Job title at your agency example: Producer drlpStates: type: array description: >- States where this producer is a Designated Responsible Licensed Producer. Applied to every association created by this request. example: - PA items: type: string enum: - AL - AK - AZ - AR - CA - CO - CT - DE - FL - GA - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - RI - SC - SD - TN - TX - UT - VT - VA - WA - WV - WI - WY - GU - PR - VI - DC entityIds: description: >- The entities to associate this producer with. Every id must be one of yours; a single foreign id fails the whole request with 404 rather than creating the associations it could. example: - 6610b3d2c2e0a51b8c0d1f02 type: array items: type: array required: - firstName - lastName - entityIds DownstreamProducerResponse: type: object properties: producerId: type: string description: Unique identifier of the producer example: 6627f2b5c2e0a51b8c0d4e7c firstName: type: string description: Given name example: Jon middleName: type: string description: Middle name example: R lastName: type: string description: Surname example: Doe npn: type: string description: National Producer Number example: '7654321' mainEmail: type: string description: The producer login email example: example@test.com nasdCrd: type: string description: FINRA CRD number example: '5551234' entities: description: The entities in your organization this producer is associated with type: array items: $ref: '#/components/schemas/DownstreamProducerEntityResponse' createdAt: type: string description: ISO 8601 creation timestamp example: '2025-01-15T10:30:00.000Z' updatedAt: type: string description: ISO 8601 last-update timestamp example: '2025-06-02T08:12:44.000Z' required: - producerId - firstName - lastName - entities 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 DownstreamProducerEntityResponse: type: object properties: associationId: type: string description: Identifier of the producer-to-entity relationship itself example: 6627f1a9c2e0a51b8c0d4e3a downstreamEntityId: type: string description: The entity this producer is associated with example: 6610b3d2c2e0a51b8c0d1f02 branchName: type: string description: Branch name of that entity example: Philadelphia Branch drlpStates: type: array description: >- States where this producer is a Designated Responsible Licensed Producer for that entity example: - PA items: type: string enum: - AL - AK - AZ - AR - CA - CO - CT - DE - FL - GA - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - RI - SC - SD - TN - TX - UT - VT - VA - WA - WV - WI - WY - GU - PR - VI - DC email: type: string description: >- Email held on this relationship, which may differ per entity. Not the producer login. example: example@test.com position: type: string description: Job title at that entity example: Producer required: - associationId - downstreamEntityId - branchName - drlpStates ```` ## Related topics - [Assign a Producer to Entities](/api-reference/v2/downstream/producers/assign-producer-entities.md) - [Add (Dangerously)](/api-reference/v1/downstream-entity-associations/dangerously-add.md) - [Add a Contact](/api-reference/v2/downstream/contacts/add-contact.md)