Skip to main content
Invalidate a signature-required message that hasn’t been signed yet. Use this endpoint to cancel pending signature requests when they’re no longer needed. When invalidated, the message remains visible to users in their UIP app, but they can no longer sign it.

​
Request

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key: Bearer YOUR_API_KEY
Content-TypeYesMust be application/json

​
Body Parameters

​
message_id
string
required
The unique message identifier returned when the message was created.Example: "msg_abc123def456"

​
When You Can Invalidate

You can only invalidate a message when all of the following conditions are true:
1

Message Exists

The message must have been successfully created via the Message API
2

Signature Required

The message must have been created with signature_required: true
3

Not Yet Signed

The recipient must not have signed or declined the message yet
Important: You cannot invalidate messages that:
  • Don’t require signatures (signature_required: false)
  • Have already been signed or declined by the recipient
  • Don’t exist or were created by a different business account

​
What Happens After Invalidation

​
Message Visibility

  • User can still see the message - The message remains in the user’s UIP app
  • Cannot be signed - The signature action is permanently disabled
  • No webhook sent - Invalidation does not trigger a webhook event

​
Use Cases for Invalidation

Request Canceled

Cancel signature requests when the underlying transaction or agreement is canceled

Wrong Recipient

Invalidate messages sent to the wrong user before they sign

Document Updated

Invalidate old signature requests when documents are revised or updated

Business Logic Changes

Cancel pending signatures when business requirements or approval workflows change

​
Response

​
Success Response (200 OK)

Returns HTTP status code 200 with no response body on successful invalidation.

​
Example Request

curl -X POST https://api.uip.digital/v1/message/invalidate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_abc123def456"
  }'

​
Example Response

HTTP/1.1 200 OK
No response body is returned on success.

​
Errors

See the Error Handling Guide for comprehensive error handling strategies. Possible error codes for this endpoint: Authentication Errors:
  • auth/missing-api-key - No API key provided in Authorization header
  • auth/invalid-api-key - Invalid API key
  • auth/revoked-api-key - API key has been revoked
  • auth/unauthorized - You do not own this message
Request Validation Errors:
  • request/invalid-payload - Request payload is invalid or missing required fields (message_id is required)
  • request/not-found - No such registered route in API service
Resource Errors:
  • resource/not-found - Message ID not found or business not found
  • resource/invalidated - Message already invalidated
  • resource/already-completed - Signature already collected, cannot invalidate
Internal Errors:
  • internal/server-error - Failed to invalidate message or process request
  • data/corrupt - Corrupt key data detected

​
Implementation Flow

1

Create Signature-Required Message

Send a message via the Message API with signature_required: true
2

Save Message ID

Store the returned message_id in your database for tracking
3

Business Logic Triggers Cancellation

When your business logic determines the signature request should be canceled (transaction canceled, wrong recipient, etc.)
4

Call Invalidate API

Send the message_id to the Invalidate endpoint to prevent signing
5

Update Internal Records

Mark the message as invalidated in your database

​
Best Practices

Invalidate Promptly

Invalidate messages as soon as you know they’re no longer needed to prevent confusion

Track Invalidation Status

Store invalidation timestamps in your database for audit trails and compliance

Handle Errors Gracefully

Check for already-signed or already-invalidated errors and handle them appropriately

User Communication

Consider notifying users separately when you invalidate their pending signature requests

​
Common Scenarios

When a transaction or agreement is canceled, invalidate pending signature requests to prevent users from signing outdated documents.
// Transaction canceled, invalidate signature request
await fetch('https://api.uip.digital/v1/message/invalidate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message_id: 'msg_abc123def456'
  })
});
When documents are updated or revised, invalidate old signature requests and send new ones with the updated documents.
// Document revised, invalidate old request
await invalidateOldRequest('msg_old123');

// Send new signature request with updated document
const newMessage = await createNewSignatureRequest({
  receiver_uip: 'user_abc123',
  intent: 'Sign Updated Employment Contract',
  signature_required: true,
  attachments: ['updated_contract.pdf']
});
If a signature request was sent to the wrong user, invalidate it before they sign to prevent legal complications.
// Sent to wrong user, invalidate immediately
await fetch('https://api.uip.digital/v1/message/invalidate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message_id: 'msg_wrong_user123'
  })
});

// Send to correct user
await sendToCorrectUser({
  receiver_uip: 'correct_user_xyz789',
  // ... rest of message parameters
});
When approval workflows or business requirements change, invalidate pending signatures that are no longer relevant.
// Workflow changed, invalidate all pending signatures
const pendingMessageIds = await getPendingSignatures();

for (const messageId of pendingMessageIds) {
  try {
    await fetch('https://api.uip.digital/v1/message/invalidate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${YOUR_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ message_id: messageId })
    });
  } catch (error) {
    // Handle already-signed or not-found errors
    console.error(`Failed to invalidate ${messageId}:`, error);
  }
}

Message API

Send encrypted messages and signature requests

Audit API

Retrieve permanent audit records

Error Handling

Handle API errors properly

Webhooks

Handle webhook events for signed messages