e-Próspera API docs

Appearance

GET /api/v1/me/natural-person/id-verification ​

Retrieve identity verification documents (ID photos and selfie) for the authenticated user.

Endpoint ​

GET /api/v1/me/natural-person/id-verification

Authentication ​

Requires a valid OAuth access token with the eprospera:person.id_verification.read scope.

Authorization: Bearer <access-token>

Required Scopes ​

  • eprospera:person.id_verification.read

Request ​

No request body or query parameters required.

Example Request ​

bash
curl https://portal.eprospera.com/api/v1/me/natural-person/id-verification \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response ​

Success Response (200 OK) ​

Returns the user's most recent approved identity verification session and pre-signed URLs to access the verification documents.

FieldTypeDescription
idstring | nullThe ID of the identity verification
typestring | nullThe verification provider type (currently always 'veriff' when session exists)
datestring | nullISO 8601 timestamp of when the verification session was created
statusstring | nullThe verification status (currently always 'approved' for returned sessions)
documentsobjectContainer for verification document URLs
documents.documentFrontstring | nullPre-signed S3 URL for the front of the ID document
documents.documentBackstring | nullPre-signed S3 URL for the back of the ID document
documents.facestring | nullPre-signed S3 URL for the selfie/face photo

Example Response ​

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "veriff",
  "date": "2024-01-15T10:30:00.000Z",
  "status": "approved",
  "documents": {
    "documentFront": "https://s3.us-east-2.amazonaws.com/bucket/path/document-front.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "documentBack": "https://s3.us-east-2.amazonaws.com/bucket/path/document-back.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "face": "https://s3.us-east-2.amazonaws.com/bucket/path/face.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
  }
}

No Verification Session Response ​

If the user has not completed identity verification or has no approved sessions:

json
{
  "id": null,
  "type": null,
  "date": null,
  "status": null,
  "documents": {
    "documentFront": null,
    "documentBack": null,
    "face": null
  }
}

Error Responses ​

401 Unauthorized - Missing Token ​

json
{
  "error": "missing_token"
}

401 Unauthorized - Invalid Token ​

json
{
  "error": "invalid_token"
}

401 Unauthorized - Insufficient Scopes ​

json
{
  "error": "missing_scopes: eprospera:person.id_verification.read"
}

500 Internal Server Error ​

json
{
  "error": "Internal server error"
}

Document URLs ​

Pre-signed URLs ​

All document URLs are pre-signed S3 URLs that:

  • Expire after 1 hour from generation
  • Allow direct download of the image files
  • Do not require additional authentication
  • Should be treated as temporary and sensitive

Document Types ​

  • documentFront: Front side of government-issued ID (passport, driver's license, national ID)
  • documentBack: Back side of ID document (may be null for passports)
  • face: Selfie photo taken during verification process

Image Format ​

  • All images are in JPEG format (.jpg)
  • Images are stored at the resolution captured during verification
  • Files are sourced from Veriff's identity verification service

Usage Notes ​

  • This endpoint returns documents from the most recent approved identity verification session
  • If a user has multiple verification sessions, only the latest approved one is returned
  • Documents are backed up to e-Próspera's secure S3 storage during the Veriff verification process
  • URLs expire after 1 hour and must be regenerated by calling the endpoint again
  • Some ID types (like passports) may only have a documentFront image
  • The face image is the selfie taken during the liveness check

Security Considerations ​

  • Pre-signed URLs provide temporary access to sensitive identity documents
  • URLs should not be logged, stored long-term, or shared
  • Documents contain personally identifiable information (PII)
  • Implement appropriate security measures when handling these documents:
    • Use HTTPS for all transfers
    • Don't cache images in insecure locations
    • Delete images after processing if not needed
    • Follow data protection regulations (GDPR, CCPA, etc.)

Data Privacy ​

  • Only the authenticated user's own documents are accessible
  • Documents are only returned if the correct scope is granted during OAuth authorization
  • Access is limited to approved verification sessions only
  • All documents are subject to e-Próspera's privacy policy
  • e-Próspera stores backup copies of verification documents for compliance purposes

Verification Status ​

This endpoint only returns documents from approved verification sessions. To check if a user has completed identity verification, you can:

  1. Call this endpoint and check if id is not null
  2. Check if documents.face is not null (indicates completed verification)

Example Integration ​

javascript
// Fetch identity verification documents
async function getIdDocuments(accessToken) {
  const response = await fetch(
    'https://portal.eprospera.com/api/v1/me/natural-person/id-verification',
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  if (!response.ok) {
    throw new Error('Failed to fetch documents');
  }

  const data = await response.json();

  if (!data.id) {
    console.log('User has not completed identity verification');
    return null;
  }

  // URLs are valid for 1 hour
  return {
    sessionId: data.id,
    type: data.type,
    date: data.date,
    status: data.status,
    documentFront: data.documents.documentFront,
    documentBack: data.documents.documentBack,
    face: data.documents.face
  };
}

// Download document to blob (for display or processing)
async function downloadDocument(signedUrl) {
  const response = await fetch(signedUrl);
  const blob = await response.blob();
  return blob;
}