🎉 Unlimited Free KYC - Forever!!

Identity Verification
API Reference
Update Status

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

ParameterTypeRequired?DescriptionExample Value
session_idstringYesThe unique identifier of the session to update."11111111-2222-3333-4444-555555555555"
new_statusstringYesThe new status to set for the session. Can be Approved or Declined."Approved", "Declined"
commentstringOptionalA 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

FieldTypeDescription
session_idstringThe unique identifier of the updated session.

Error Handling

Status CodeErrorDescription
400Bad RequestMissing or invalid parameters.
401UnauthorizedInvalid or missing access_token.
403ForbiddenNot authorized to update this session's status.
404Not FoundSession ID not found or invalid.
409ConflictThe 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;
  }
};
import requests
 
def update_session_status(session_id, new_status, comment=None):
    """
    Update the status of a verification session.
 
    Args:
        session_id (str): The ID of the verification session.
        new_status (str): The new status ('Approved' or 'Declined').
        comment (str, optional): Optional comment explaining the status change.
 
    Returns:
        dict: The response data or None if an error occurred.
    """
    url = f"https://verification.didit.me/v1/session/{session_id}/update-status/"
    token = get_client_token()  # Implement this function based on auth documentation
 
    if not token:
        print("Error: Failed to authenticate")
        return None
 
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token['access_token']}"
    }
 
    # Prepare request body
    body = {
        "new_status": new_status
    }
 
    if comment:
        body["comment"] = comment
 
    try:
        response = requests.patch(url, headers=headers, json=body)
        response.raise_for_status()
 
        return response.json()
 
    except requests.RequestException as e:
        print(f"Error updating session status: {e}")
        try:
            error_detail = e.response.json().get('detail', str(e))
            print(f"Server returned: {error_detail}")
        except:
            pass
        return None

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);
  }
}