> ## 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. # Request a Diligent-Effort Signature > Send a state's diligent-effort form to somebody at one of your agencies Sends the named person at one of your agencies the state diligent-effort (declination) form to sign, and returns the request with its live DocuSign envelope. `upstreamDownstreamAssociationId` must name one of your own agency relationships. Anything else returns **404**, the same answer you get for an id that does not exist at all. ## Quote ID and Type `quoteId` is your own identifier for the quote this form is being raised against — whatever your system calls it: control number, prospect number, or quote number. **It must be unique within your organisation.** Sending a `quoteId` you have already used on a previous request returns **409**, naming the field. `quoteType` says whether the quote is new business or a renewal. Both fields are required and both are echoed back on the response, unchanged. ## The document is ours, not yours The form is Turris's published diligent-effort form for the state you name, and its exact version is frozen onto the request the moment it is sent. Republishing the state's form later never reshapes a request already in flight, so a signed document always matches what its signer saw. You cannot select a document, and there is no field to pass one. ## When a state's form is not ready A **422** means Turris cannot send that state's form right now. `details.refusalCode` says which of four reasons applies and the message says what happens next: Turris holds no form for that state yet. The state has a record but no uploaded form to build from. The form exists but is not published for sending. Somebody is editing the form right now. Try again shortly. Branch on the code, show the message. The two are both in every 422 body for exactly that split. ## How the recipient is identified Name them by email. If Turris already holds a contact for that address at that agency, it is used. Otherwise send `recipientFirstName` and `recipientLastName` and a contact is created; omit either one in that case and you get a **400**. The address is checked before anything is created. One email is the only notification the signer ever gets, so an address whose mailbox does not exist is refused with a **400** carrying `errorType: invalid_email` rather than producing a request nobody will answer. ## The name on the signed document may not be the name you sent Where Turris already holds a name for an address, **that stored name is what appears on the signed document**, and the name in your response is an echo of what you sent. So a request naming "Bob Smith" for an address Turris holds as "Robert Smith" comes back saying "Bob Smith" while the signed form says "Robert Smith". The response is authoritative for your own request, not a read of our records: we do not return names we hold for addresses you have not registered yourself. ## What the recipient receives One email from Turris with a link to sign in and sign. **Nothing is sent to them from DocuSign.** The signature is taken inside Turris against their own authenticated session, which is what stops whoever opens their mailbox from signing on their behalf. If they are not a Turris user yet, the link enrols them. Send an `Idempotency-Key` header. See [Idempotency](/guides/idempotency). ## OpenAPI ````yaml openapi/v2.json POST /v2/upstream/diligent-effort-requests 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/diligent-effort-requests: post: tags: - upstream/diligent-effort-requests summary: Request a diligent-effort form signature description: >- Sends the named agency contact the state diligent-effort (declination) form for signature. The document is Turris's published form for that state, frozen onto the request at send, so a later republication never reshapes a request already in flight. The recipient is emailed a link to sign in and sign; nothing is sent to them from DocuSign. If Turris holds no contact for the address at that agency, send recipientFirstName and recipientLastName and one is created. operationId: DiligentEffortRequestsV2Controller_createDiligentEffortRequest_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/CreateDiligentEffortRequestDto' responses: '201': description: The request, with its live DocuSign envelope content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DiligentEffortRequestResponse' 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, a recipient name is missing for an address you have no contact for at that agency, or the recipient address is not a real mailbox (`errorType: invalid_email`) 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: No such association for your organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '409': description: >- A diligent effort request already exists for this quoteId within your organisation, or this request stopped being sendable between validation and send (most commonly a duplicate delivery of this same call arriving while the first was still in flight) content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '422': description: >- Turris's diligent-effort form for that state is not ready to send. `details.refusalCode` says which of the four reasons applies and the message says what happens next. content: application/json: schema: $ref: '#/components/schemas/DiligentEffortRefusalResponse' components: schemas: CreateDiligentEffortRequestDto: type: object properties: upstreamDownstreamAssociationId: type: string description: >- The carrier-agency relationship to raise the request under. Must be one of your own associations; anything else is treated as not found. example: 6610b3d2c2e0a51b8c0d1f02 stateCode: type: string description: >- The state or territory whose diligent-effort form to send. Turris must have a published form for it. 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 example: CA quoteId: type: string description: >- Your own identifier for the quote this form is being raised against. Whatever your system calls it: control number, prospect number, or quote number. Must be unique within your organisation. example: Q-10045 maxLength: 100 quoteType: type: string description: Whether the quote is new business or a renewal. enum: - new quote - renewal quote example: new quote recipientEmail: type: string description: >- Who at the agency should sign. If Turris already holds a contact for this address at that agency it is used; otherwise a contact is created, which is when the name fields below are required. example: casey.rivera@example-agency.com recipientFirstName: type: string description: >- The recipient's first name. Required when Turris holds no contact for this address at the agency. When it does, the stored name is what appears on the signed document, and this value is echoed back to you unchanged. example: Casey recipientLastName: type: string description: >- The recipient's last name. Required when Turris holds no contact for this address at the agency. When it does, the stored name is what appears on the signed document, and this value is echoed back to you unchanged. example: Rivera required: - upstreamDownstreamAssociationId - stateCode - quoteId - quoteType - recipientEmail DiligentEffortRequestResponse: type: object properties: _id: type: string description: Unique identifier of the diligent-effort request example: 6650a1b2c3d4e5f6a7b8c9d0 upstreamDownstreamAssociationId: type: string description: The carrier-agency relationship the request was raised under example: 6610b3d2c2e0a51b8c0d1f02 downstreamEntityId: type: string description: The agency asked to sign, resolved from the association example: 6610b3d2c2e0a51b8c0d1f03 stateCode: type: string description: US state or territory whose diligent-effort form was sent 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 example: CA quoteId: type: string description: >- Your own identifier for the quote this form was raised against, echoed back example: Q-10045 quoteType: type: string description: Whether the quote is new business or a renewal enum: - new quote - renewal quote example: new quote status: type: string description: Lifecycle status. Always `sent` on a successful create enum: - draft - sent - signed - declined - voided example: sent recipientEmail: type: string description: The address the form was sent to, normalized as stored example: casey.rivera@example-agency.com recipientFirstName: type: string description: >- Echo of the first name you sent, or null when you sent none. Not a read of the stored contact: where Turris already held a name for this address, that stored name is what appears on the signed document. nullable: true example: Casey recipientLastName: type: string description: >- Echo of the last name you sent, or null when you sent none. Not a read of the stored contact: where Turris already held a name for this address, that stored name is what appears on the signed document. nullable: true example: Rivera docusignEnvelopeId: type: string description: The live DocuSign envelope. Always present on a successful create nullable: true example: 3f2a1c9e-8b7d-4e5f-9a0b-1c2d3e4f5a6b createdAt: type: string description: ISO 8601 creation timestamp example: '2026-09-14T10:15:00.000Z' required: - _id - upstreamDownstreamAssociationId - downstreamEntityId - stateCode - quoteId - quoteType - status - recipientEmail - createdAt 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 DiligentEffortRefusalResponse: 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: description: >- Why the state's diligent-effort form cannot be sent against right now. allOf: - $ref: '#/components/schemas/DiligentEffortRefusalDetailsResponse' required: - statusCode - requestId - errorType - errorMessage - timestamp - details DiligentEffortRefusalDetailsResponse: type: object properties: refusalCode: type: string description: >- Which of the four reasons the state form cannot be sent against. Branch on this; show errorMessage to a person. enum: - STATE_FORM_NOT_FOUND - STATE_FORM_FILE_MISSING - STATE_FORM_NOT_PUBLISHED - STATE_FORM_BEING_EDITED example: STATE_FORM_NOT_PUBLISHED required: - refusalCode 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 - [Diligent Effort Form Status Change](/guides/webhooks/diligent-effort-form-status-change.md) - [Rate Limiting](/guides/rate-limiting.md) - [Webhooks Overview](/guides/webhooks.md)