Skip to main content
POST
Request a diligent-effort form signature
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
​
upstreamDownstreamAssociationId
string
required

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
enum<string>
required

The state or territory whose diligent-effort form to send. Turris must have a published form for it.

Available options:
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
string
required

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.

Maximum string length: 100
Example:

"Q-10045"

​
quoteType
enum<string>
required

Whether the quote is new business or a renewal.

Available options:
new quote,
renewal quote
Example:

"new quote"

​
recipientEmail
string
required

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
string

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
string

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"

Response

The request, with its live DocuSign envelope

​
data
object
required
​
requestId
string
required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

​
timestamp
string
required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"