Updating a Verification Session Status
To update the status of a verification session, you can call the /v1/session/{sessionId}/update-status/
endpoint.
- Base URL:
https://verification.didit.me
- Endpoint:
/v1/session/{sessionId}/update-status/
- Method:
PATCH
- Authentication:
Client Token (Bearer Token)
The authentication endpoint uses a different base URL than the verification session endpoints. Ensure you use the correct URLs to avoid connectivity issues.
Request
Follow these steps to update a verification session status programmatically:
Step 1: Authenticate
Obtain a valid access_token
by following the Authentication documentation. This token is required in the Authorization
header of your request.
The access_token
is valid for 24 hours. You only need to re-authenticate once it expires.
Step 2: Prepare Request Parameters
Parameter | Type | Required? | Description | Example Value |
---|---|---|---|---|
|
| Yes | The unique identifier of the session to update. | "11111111-2222-3333-4444-555555555555" |
|
| Yes | The new status to set for the session. Can be Approved or Declined . | "Approved" , "Declined" |
|
| Optional | A comment explaining the reason for the status change. | "Duplicated user" , "Manual verification complete" |
Step 3: Send the Request
Make a PATCH
request to /v1/session/{session_id}/update-status/
with the required parameters.
Example Request
PATCH /v1/session/11111111-2222-3333-4444-555555555555/update-status/ HTTP/1.1
Host: verification.didit.me
Content-Type: application/json
Authorization: Bearer {access_token}
{
"new_status": "Approved",
"comment": "Manually verified by compliance team"
}
Response
The response returns a confirmation of the updated session.
Example Response
{
"session_id": "11111111-2222-3333-4444-555555555555"
}
Response Fields
Field | Type | Description |
---|---|---|
|
| The unique identifier of the updated session. |
Error Handling
Status Code | Error | Description |
---|---|---|
400 | Bad Request | Missing or invalid parameters. |
401 | Unauthorized | Invalid or missing access_token. |
403 | Forbidden | Not authorized to update this session's status. |
404 | Not Found | Session ID not found or invalid. |
409 | Conflict | The session is already in the requested status. |
Example Error Response
{
"detail": "Invalid status value. Must be 'Approved' or 'Declined'."
}
Status Update Use Cases
This endpoint is useful for:
- Manual Review: Updating sessions that were flagged for manual review
- Compliance Override: Allowing compliance officers to override automatic decisions
- Exception Handling: Approving users who failed automated checks but are valid cases
- Fraud Prevention: Declining sessions after detecting suspicious patterns
All status updates create a review record in the session history, tracking who made the change and when.
Code Examples
const updateSessionStatus = async (
sessionId,
newStatus,
comment = null
) => {
const endpoint = `https://verification.didit.me/v1/session/${sessionId}/update-status/`;
const token = await getClientToken();
if (!token) {
console.error('Error fetching client token');
throw new Error('Authentication failed');
}
const body = {
new_status: newStatus
};
if (comment) {
body.comment = comment;
}
const headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token.access_token}`
};
try {
const response = await fetch(endpoint, {
method: 'PATCH',
headers,
body: JSON.stringify(body)
});
if (!response.ok) {
const errorData = await response.json();
console.error('Error updating session status:', errorData.detail || errorData.message);
throw new Error(errorData.detail || 'Failed to update session status');
}
const data = await response.json();
return data;
} catch (err) {
console.error('Error:', err);
throw err;
}
};
Implementing a Review System
Below is an example of how you might implement a review system using this endpoint:
// This function handles the UI action when a reviewer approves a verification
async function handleApproveVerification(sessionId, reason) {
try {
// Update the session status to Approved
const result = await updateSessionStatus(
sessionId,
'Approved',
reason || 'Manually approved after review'
);
if (result && result.session_id) {
// Update your local database to reflect this change
await updateUserVerificationStatus(
result.session_id,
'approved',
{
reviewedBy: getCurrentUser().email,
reviewDate: new Date().toISOString(),
reviewNotes: reason
}
);
// Notify the user if applicable
await sendVerificationApprovalEmail(sessionId);
// Update the UI
showSuccessNotification('Verification approved successfully');
reloadReviewQueue();
}
} catch (error) {
console.error('Failed to approve verification:', error);
showErrorNotification('Failed to approve verification: ' + error.message);
}
}
// This function handles the UI action when a reviewer declines a verification
async function handleDeclineVerification(sessionId, reason) {
if (!reason) {
showErrorNotification('A reason is required when declining a verification');
return;
}
try {
// Update the session status to Declined
const result = await updateSessionStatus(
sessionId,
'Declined',
reason
);
if (result && result.session_id) {
// Update your local database to reflect this change
await updateUserVerificationStatus(
result.session_id,
'declined',
{
reviewedBy: getCurrentUser().email,
reviewDate: new Date().toISOString(),
reviewNotes: reason
}
);
// Notify the user if applicable
await sendVerificationDeclinedEmail(sessionId, reason);
// Update the UI
showSuccessNotification('Verification declined');
reloadReviewQueue();
}
} catch (error) {
console.error('Failed to decline verification:', error);
showErrorNotification('Failed to decline verification: ' + error.message);
}
}