Skip to main content
GET
{base_url}
/
otk-service
/
v1
/
residents
/
stale
Stale Residents
curl --request GET \
  --url https://api.example.com/{base_url}/otk-service/v1/residents/stale \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'x-transaction-key: <x-transaction-key>'
{
    "success": true,
    "data": {
        "uaekyc_ids": [12001, 12002, 12003]
    },
    "message": "Stale residents retrieved successfully",
    "signature": "abc123...",
    "meta": {
        "timestamp": "2025-05-13T11:00:28.541Z",
        "filters": {
            "from_date": "2025-01-01",
            "to_date": "2025-12-31"
        },
        "pagination": {
            "total_count": 3,
            "page": 1,
            "page_size": 50,
            "has_more": false
        }
    },
    "errors": []
}
Deprecation Notice: This polling-based API will be deprecated in a future release. We recommend migrating to the Proactive Record Status Service - PRESS webhook-based notification system for alerts when customer records change.
This API retrieves customers whose government records have changed and who require re-verification (Re-KYC).
Key Points
  • The start_date must be earlier than or equal to the end_date.
  • Date formats must follow the YYYY-MM-DD pattern.
  • The maximum allowed page_size is 100.
  • For large result sets, use pagination by incrementing the page parameter.

​
Authentication

​
x-transaction-key
string
required
Your API key. Get your key →
​
Accept
string
required
Must be application/json
​
Content-Type
string
required
Must be application/json

​
Query Parameters

​
start_date
string
required
Start date for the search range. Format: YYYY-MM-DD (10 characters). Must be earlier than or equal to end_date.
​
end_date
string
required
End date for the search range. Format: YYYY-MM-DD (10 characters).
​
page
integer
default:"1"
Page number for pagination. Minimum: 1.
​
page_size
integer
default:"50"
Number of results per page. Range: 1–100.

​
Code Examples

curl "{base_url}/otk-service/v1/residents/stale?start_date=2024-01-01&end_date=2025-12-31&page=1&page_size=50" \
  -H "x-transaction-key: your-api-key" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

​
Response Fields

Response Structure
{
  "success": true,
  "data": { ... },         // Stale resident IDs
  "message": "...",
  "signature": "...",
  "meta": { ... },
  "errors": []
}
FieldTypePresenceDescription
successbooleanAlwaysWhether the request was successful.
messagestringAlwaysHuman-readable status message.
data.uaekyc_idsinteger[]AlwaysList of UAE KYC IDs requiring re-verification. Empty array when none found. Pass each as uaeKycId in the Create Journey API to initiate Re-KYC journeys.
signaturestringAlwaysCryptographic signature for response verification.
meta.timestampstring (ISO 8601)AlwaysServer timestamp.
meta.filters.from_datestringAlwaysThe start date used in the query (YYYY-MM-DD).
meta.filters.to_datestringAlwaysThe end date used in the query (YYYY-MM-DD).
meta.pagination.total_countintegerAlwaysTotal number of results.
meta.pagination.pageintegerAlwaysCurrent page number.
meta.pagination.page_sizeintegerAlwaysNumber of results per page.
meta.pagination.has_morebooleanAlwaystrue if additional pages are available.
errorsarrayAlwaysList of error objects. Each contains code, type, and message.

​
Next Steps

1
Trigger Re-KYC journeys
2
Each ID in uaekyc_ids represents a customer whose verification is outdated. Create a Re-KYC journey using the Create Journey API with journeyType: "REKYC" and the customer’s uaeKycId.
3
Paginate through all results
4
If has_more is true, increment the page parameter and continue fetching until all stale residents are retrieved.
5
Run on a schedule
6
Set up a recurring job (daily or weekly) to call this API and identify customers needing re-verification.
{
    "success": true,
    "data": {
        "uaekyc_ids": [12001, 12002, 12003]
    },
    "message": "Stale residents retrieved successfully",
    "signature": "abc123...",
    "meta": {
        "timestamp": "2025-05-13T11:00:28.541Z",
        "filters": {
            "from_date": "2025-01-01",
            "to_date": "2025-12-31"
        },
        "pagination": {
            "total_count": 3,
            "page": 1,
            "page_size": 50,
            "has_more": false
        }
    },
    "errors": []
}