--- title: "Updates signer email or phone for a case while e-signature is pending upstream." url: "https://developers.zinnia.com/apis/market-connect-order-entry/versions/50f981c3-db50-4358-884f-31eb427255ec/operations/updateEsignSignerDetails" --- > Full API specification: https://developers.zinnia.com/apis/market-connect-order-entry/versions/50f981c3-db50-4358-884f-31eb427255ec.md # Updates signer email or phone for a case while e-signature is pending upstream. `POST` `/market-connect/order-entry/v1/esignature/update-signer` Operation ID: `updateEsignSignerDetails` #### Error Responses - **400 Bad Request** - ```VALIDATION_ERROR``` - The request failed input validation. - **401 Unauthorized** - ```UNAUTHORIZED``` - Authentication failed or the access token is missing, expired, or invalid. - **403 Forbidden** - ```FORBIDDEN``` - The authenticated user is not authorized to access this resource. - **404 Not Found** - ```TRANSACTION_ID_NOT_FOUND``` - No transaction exists for the specified transaction ID. - **429 Too Many Requests** - ```RATE_LIMIT_EXCEEDED``` - The client has exceeded the permitted request rate or quota. - **500 Internal Server Error** - ```UNEXPECTED_ERROR``` - An unexpected internal system error occurred while processing the request. - **502 Bad Gateway** - ```UPSTREAM_SERVICE_ERROR``` - An upstream dependency returned an invalid or unsuccessful response. - **503 Service Unavailable** - ```SERVICE_UNAVAILABLE``` - The service or a required dependency is temporarily unavailable. - **504 Gateway Timeout** - ```UPSTREAM_TIMEOUT``` - A required downstream service did not respond within the configured timeout. #### Standard Error Response All error responses conform to the standard ```ErrorResponse``` schema and include: - A stable error code from ```ErrorInfo.code```. - A human-readable error message. - Optional diagnostic details, when applicable. - A timestamp indicating when the error occurred. This consistent format enables clients to implement standardized error processing, logging, and troubleshooting across all Order Entry API endpoints. ## Request body (required) Content types: `application/json` ## Responses - `200` - Returns the update result envelope - `400` - `VALIDATION_ERROR` - The request failed input validation. `INVALID_TRANSACTION_ID` - The supplied transaction ID is invalid (less than or equal to zero). - `401` - `UNAUTHORIZED` - Authentication failed or the access token is missing, expired, or invalid. - `403` - `FORBIDDEN` - The authenticated user is not authorized to access the requested transaction. - `404` - `TRANSACTION_ID_NOT_FOUND` - No transaction exists for the specified transaction ID. `NOT_FOUND` - The requested transaction or blueprint step could not be found. - `429` - `RATE_LIMIT_EXCEEDED` - The client has exceeded the permitted request rate or quota. - `500` - `BUILD_BLUEPRINT_ERROR` - An error occurred while generating the order entry blueprint. `JSON_PARSE_ERROR` - The system encountered an error while parsing the transaction response. `UNEXPECTED_ERROR` - An unexpected internal system error occurred while processing the request. - `502` - `UPSTREAM_SERVICE_ERROR` - An upstream dependency returned an invalid or unsuccessful response. - `503` - `SERVICE_UNAVAILABLE` - The service or a required dependency is temporarily unavailable. - `504` - `UPSTREAM_TIMEOUT` - A required downstream service did not respond within the configured timeout. ## OpenAPI definition ````yaml openapi: 3.0.1 info: title: Market Connect Order Entry API version: 1.0.3 servers: - url: https://dev.api.zinnia.io - url: https://qa.api.zinnia.io - url: https://uat.api.zinnia.io paths: /market-connect/order-entry/v1/esignature/update-signer: post: tags: - Esignature summary: Updates signer email or phone for a case while e-signature is pending upstream. description: >- #### Error Responses - **400 Bad Request** - ```VALIDATION_ERROR``` - The request failed input validation. - **401 Unauthorized** - ```UNAUTHORIZED``` - Authentication failed or the access token is missing, expired, or invalid. - **403 Forbidden** - ```FORBIDDEN``` - The authenticated user is not authorized to access this resource. - **404 Not Found** - ```TRANSACTION_ID_NOT_FOUND``` - No transaction exists for the specified transaction ID. - **429 Too Many Requests** - ```RATE_LIMIT_EXCEEDED``` - The client has exceeded the permitted request rate or quota. - **500 Internal Server Error** - ```UNEXPECTED_ERROR``` - An unexpected internal system error occurred while processing the request. - **502 Bad Gateway** - ```UPSTREAM_SERVICE_ERROR``` - An upstream dependency returned an invalid or unsuccessful response. - **503 Service Unavailable** - ```SERVICE_UNAVAILABLE``` - The service or a required dependency is temporarily unavailable. - **504 Gateway Timeout** - ```UPSTREAM_TIMEOUT``` - A required downstream service did not respond within the configured timeout. #### Standard Error Response All error responses conform to the standard ```ErrorResponse``` schema and include: - A stable error code from ```ErrorInfo.code```. - A human-readable error message. - Optional diagnostic details, when applicable. - A timestamp indicating when the error occurred. This consistent format enables clients to implement standardized error processing, logging, and troubleshooting across all Order Entry API endpoints. operationId: updateEsignSignerDetails requestBody: description: Transaction ID and signer rows with corrected email and/or phone while e-signature is pending upstream. content: application/json: schema: allOf: - $ref: "#/components/schemas/UpdateEsignSignerDetailsRequest" example: transactionId: 1131068 signers: - recipientId: "11306862" signerEmail: corrected.email@everglades.com signerSequence: "1" signerAuthMethod: Phone signerCountryCode: "1" signerPhoneNo: "8650827071" example: transactionId: 1131068 signers: - recipientId: "11306862" signerEmail: corrected.email@everglades.com signerSequence: "1" signerAuthMethod: Phone signerCountryCode: "1" signerPhoneNo: "8650827071" required: true responses: "200": description: Returns the update result envelope content: application/json: schema: $ref: "#/components/schemas/UpdateEsignSignerDetailsResponse" examples: success: summary: Signer details updated description: success = true when corrected contact details were saved upstream. value: success: true message: Signer contact details updated successfully. business-failure: summary: Update rejected description: success = false when e-sign is not pending or upstream validation fails. value: success: false message: Signer details cannot be updated unless e-signature is pending. "400": description: >- `VALIDATION_ERROR` - The request failed input validation. `INVALID_TRANSACTION_ID` - The supplied transaction ID is invalid (less than or equal to zero). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "1131068" errors: - code: VALIDATION_ERROR description: Invalid request body details: At least one signer is required timestamp: 2026-05-18T14:30:00.0000000Z "401": description: "`UNAUTHORIZED` - Authentication failed or the access token is missing, expired, or invalid." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UNAUTHORIZED description: Unauthorized access details: The request requires authentication timestamp: 2025-01-16T13:21:19.4355657Z "403": description: "`FORBIDDEN` - The authenticated user is not authorized to access the requested transaction." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: FORBIDDEN description: Access denied details: You do not have permission to access this resource timestamp: 2025-01-16T13:21:19.4355657Z "404": description: >- `TRANSACTION_ID_NOT_FOUND` - No transaction exists for the specified transaction ID. `NOT_FOUND` - The requested transaction or blueprint step could not be found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "1131068" errors: - code: NOT_FOUND description: Resource not found details: E-signature signer update not found for transaction 1131068 timestamp: 2026-05-18T14:30:00.0000000Z "429": description: "`RATE_LIMIT_EXCEEDED` - The client has exceeded the permitted request rate or quota." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: RATE_LIMIT_EXCEEDED description: Request rate limit exceeded details: The client has exceeded the permitted request rate or quota. timestamp: 2025-01-16T13:21:19.4355657Z "500": description: >- `BUILD_BLUEPRINT_ERROR` - An error occurred while generating the order entry blueprint. `JSON_PARSE_ERROR` - The system encountered an error while parsing the transaction response. `UNEXPECTED_ERROR` - An unexpected internal system error occurred while processing the request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UNEXPECTED_ERROR description: An unexpected error occurred details: An internal error occurred. Please contact support if the problem persists. timestamp: 2025-01-16T13:21:19.4355657Z "502": description: "`UPSTREAM_SERVICE_ERROR` - An upstream dependency returned an invalid or unsuccessful response." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "1131068" errors: - code: UPSTREAM_SERVICE_ERROR description: E-signature service error details: Failed to update e-signature signer details timestamp: 2026-05-18T14:30:00.0000000Z "503": description: "`SERVICE_UNAVAILABLE` - The service or a required dependency is temporarily unavailable." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: SERVICE_UNAVAILABLE description: Service unavailable details: The service or a required dependency is temporarily unavailable. timestamp: 2025-01-16T13:21:19.4355657Z "504": description: "`UPSTREAM_TIMEOUT` - A required downstream service did not respond within the configured timeout." content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: transactionId: "12345" errors: - code: UPSTREAM_TIMEOUT description: Upstream timeout details: A required downstream service did not respond within the configured timeout. timestamp: 2025-01-16T13:21:19.4355657Z security: - openIdConnect: [] components: schemas: UpdateEsignSignerDetailsRequest: required: - signers type: object properties: transactionId: minimum: 1 type: integer description: Transaction (case) identifier whose signer contact details should be updated. format: int64 signers: minItems: 1 type: array items: $ref: "#/components/schemas/UpdateEsignSignerRequest" description: Signer rows with corrected email and/or phone while e-sign is pending. additionalProperties: false example: transactionId: 1131068 signers: - recipientId: "11306862" signerEmail: corrected.email@everglades.com signerSequence: "1" signerAuthMethod: Phone signerCountryCode: "1" signerPhoneNo: "8650827071" UpdateEsignSignerDetailsResponse: type: object properties: success: type: boolean description: True when signer contact details were updated (e-sign must be pending upstream). message: type: string description: User-safe message confirming the update or describing a failure. nullable: true additionalProperties: false example: success: true message: Signer contact details updated successfully. ErrorResponse: required: - errors - transactionId type: object properties: transactionId: minLength: 1 type: string errors: type: array items: $ref: "#/components/schemas/ErrorInfo" additionalProperties: false example: transactionId: "12345" errors: - code: UNAUTHORIZED description: Unauthorized access details: The request requires authentication timestamp: 2025-01-16T13:21:19.4355657Z UpdateEsignSignerRequest: type: object properties: recipientId: type: string description: DocuSign recipient ID from GET signers or signer status. nullable: true signerEmail: type: string description: Corrected signer email address. nullable: true signerSequence: type: string description: Signing order when routing is sequential. nullable: true signerAuthMethod: type: string description: Auth method for the signer (for example Phone or SMS). nullable: true signerCountryCode: type: string description: Country calling code (default 1 for US). nullable: true signerPhoneNo: type: string description: Corrected phone digits only; stored without dashes. nullable: true additionalProperties: false ErrorInfo: required: - code - timestamp type: object properties: code: enum: - VALIDATION_ERROR - INVALID_TRANSACTION_ID - INVALID_STEP_NAME - TRANSACTION_CREATION_FAILED - TRANSACTION_ID_NOT_FOUND - SAVE_TRANSACTION_ERROR - SAVE_TRANSACTION_FAILED - INVALID_RESPONSE_FORMAT - BUILD_BLUEPRINT_ERROR - JSON_PARSE_ERROR - TRANSFORMER_NULL_RESPONSE - EMPTY_BLUEPRINT - UNEXPECTED_ERROR - SERVICE_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - RATE_LIMIT_EXCEEDED - UPSTREAM_SERVICE_ERROR - SERVICE_UNAVAILABLE - UPSTREAM_TIMEOUT - FIRST_STEP_SETUP_FAILED - METHOD_NOT_ALLOWED type: string description: Backend error codes returned by the Order Entry API indicating validation failures, transaction issues, blueprint generation errors, authorization errors, or unexpected system failures. description: type: string nullable: true details: type: string nullable: true timestamp: type: string format: date-time additionalProperties: false example: code: VALIDATION_ERROR description: Validation failed for field '$.fieldName' details: The request contains an unrecognized property. Only documented fields are allowed. timestamp: 2024-01-15T10:30:00.000Z securitySchemes: openIdConnect: type: openIdConnect description: "OpenID Connect via Auth0. Clients present a JWT bearer token issued by the tenant in the `Authorization: Bearer ` header." openIdConnectUrl: https://login.qa.zinnia.com/.well-known/openid-configuration x-kong-security-openid-connect: config: auth_methods: - bearer verify_signature: true ignore_signature: [] consumer_claim: - sub consumer_optional: true ````