DeviceInsights: MobileGator SMS Extraction API¶

The SMS Extraction API provides programmatic access to extract structured features from SMS messages. This endpoint accepts SMS message data as input and returns extracted features such as transaction patterns, merchant information, financial data, and other relevant metadata parsed from the message content.

Base URL¶

https://deviceinsights.credeau.com

Variables¶

The following variables will be referenced throughout this documentation:

Variable	Description	Format	Source
`client_id`	Unique identifier for your organization	Alphanumeric string	Provided by Credeau during onboarding
`auth_token`	Secret token for API authentication	Alphanumeric string	Provided by Credeau during onboarding
`user_id`	Unique identifier for an end user	Alphanumeric string, max 64 chars, non-PII	Generated by your application

⚠️ Note

Keep these credentials secure and never share them publicly. These credentials are unique to your organization and will be used to authenticate all API requests.

Endpoints¶

Fetch Extracted SMS¶

POST /api/fetch_extracted_data

Authentication¶

The API requires two authentication headers:

Header	Value
`x-client-id`	`<client_id>`
`x-auth-token`	`<auth_token>`

Request Parameters¶

Request Body (JSON)¶

Parameter	Type	Required	Description
`user_id`	string	Yes	Unique identifier of the user
`client_id`	string	Yes	Client identifier (must match x-client-id header)
`cnt_sms_threshold`	int	No	Threshold on the number of SMS to fetch & extract

Request cURL¶

curl --location 'https://deviceinsights.credeau.com/api/fetch_extracted_data' \
--header 'x-client-id: <client_id>' \
--header 'x-auth-token: <auth_token>' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "<user_id>",
    "client_id": "<client_id>",
    "cnt_sms_threshold": 5000
}'

Response¶

Response Fields (JSON)¶

Field Name	Type	Description
`extracted_sms_data`	array[map[string]Object]	Array of extracted sms entries

Success Responses¶

HTTP 200 OK (Success)¶

The API returns different response structures based on the user data availability.

Case 1: User Data Available

When user data is successfully processed and features are generated:

{
    "extracted_sms_data": [
        {
            "_id": "68d64205e4a336675ab707c6",
            "user_id": "<user_id>",
            "client_id": "<client_id>",
            "request_id": "9c8d583b51334515a6ae3dfe8cb333ce",
            "sms_id": "1345",
            "sms_sender": "sbiupi",
            "sms_inbox_date": "2025-09-22 16:27:01",
            "sms_body": "dear upi user a/c x3028 debited by 80.0 on date 22sep25 trf to vinod kumar sah refno 000000642062 if not u? call-0000001109 for other services-18001234-sbi",
            "created_at": "2025-09-26 07:34:29",
            "created_date": "2025-09-26",
            "is_classified": true,
            "is_extracted": true,
            "account_last_digits": "3028",
            "transaction": 80.0,
            "transaction_party": "vinod kumar sah",
            "sms_sub_type": "bank",
            "sms_type": "account_debit_executed",
            "sender_name": "state bank of india",
            "sender_type": "bank",
            "sms_nlp_tag": "account_debit_executed_transfer_out",
            "unique_pan": "bank | state bank of india | 28",
            "is_transactional": true,
            "transaction_type": "debit-transaction",
            "acc_number_nlp": "x3028",
            "transaction_nlp": 80.0,
            "unique_pan_nlp": "bank | state bank of india | 28"
        },
        {
            "_id": "68d64205e4a336675ab707c7",
            "user_id": "<user_id>",
            "client_id": "<client_id>",
            "request_id": "9c8d583b51334515a6ae3dfe8cb333ce",
            "sms_id": "1342",
            "sms_sender": "pnbsms",
            "sms_inbox_date": "2025-09-21 14:08:03",
            "sms_body": "you have successfully registered for upi payment on pnb. if not you, please report immediately to your bank helpline no 00000000. do not share your card details/otp/atm pin with anyone.",
            "created_at": "2025-09-26 07:34:29",
            "created_date": "2025-09-26",
            "template_hash": "1866580b-277c-4391-be9f-a54891c84acc",
            "is_classified": true,
            "is_extracted": false,
            "sms_sub_type": "not_in_the_list",
            "sms_type": "not_in_the_list",
            "sender_name": "punjab national bank",
            "sender_type": "bank",
            "sms_nlp_tag": "other_notification_bank",
            "is_transactional": false,
            "unique_pan_nlp": "bank | punjab national bank | -1"
        },
        {
            "_id": "68d64205e4a336675ab707c8",
            "user_id": "<user_id>",
            "client_id": "<client_id>",
            "request_id": "9c8d583b51334515a6ae3dfe8cb333ce",
            "sms_id": "1341",
            "sms_sender": "airbnk",
            "sms_inbox_date": "2025-09-21 13:54:21",
            "sms_body": "txn of rs. 5000 using airtel payments bank card 8756 declined due to incorrect pin attempts. your card is temporary blocked. if not you, call 000000400",
            "created_at": "2025-09-26 07:34:29",
            "created_date": "2025-09-26",
            "is_classified": false,
            "is_extracted": false,
            "sender_name": "airtel payments bank",
            "sender_type": "bank",
            "sms_nlp_tag": "transaction_delined",
            "is_transactional": false,
            "unique_pan_nlp": "bank | airtel payments bank | -1"
        }
    ]
}

Case 2: User Data Not Available

When the API is called before user data is synced from the SDK or when data synchronization failed due to technical issues (such as network connectivity problems, app crashes, missing permissions, or abrupt app termination) -

{
    "extracted_sms_data": []
}

Error Responses¶

HTTP 401 Unauthorized (Wrong credentials)¶

This error occurs when either an invalid client ID or authentication token is provided in the request headers. The response includes a request ID that can be used for troubleshooting.

{
    "error": "Could not validate credentials. (request_id=<request_id>). It has been logged successfully on our servers. Please contact us with the request_id for assistance."
}

⚠️ Note

If you receive this error:

Verify that you're using the correct client ID and authentication token

Contact Credeau support with the request_id for assistance

HTTP 403 Forbidden (Invalid Access)¶

This error can occur in two scenarios:

IP Not Whitelisted: When the requesting IP address is not whitelisted in the Credeau firewall. For security reasons, all API requests must originate from pre-approved IP addresses.
Incorrect API Path: When an incorrect or misspelled API path is used in the request URL.

<html>
    <head><title>403 Forbidden</title></head>
    <body>
        <center><h1>403 Forbidden</h1></center>
    </body>
</html>

⚠️ Note

To resolve this error:

Verify that you're using the correct API endpoint path

If the path is correct, contact Credeau support to whitelist your IP address

Provide your organization's name and the IP address(es) that need access

Once whitelisted, you'll be able to access the API from the approved IP addresses

HTTP 422 Unprocessable Content (Wrong Request Payload)¶

This error is returned when any of the required parameters (user_id, client_id, or groupings) is missing from the request payload. The response includes details about which fields are missing and the received input.

{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "body",
                "user_id"
            ],
            "msg": "Field required",
            "input": {
                "client_id": "<client_id>",
                "cnt_sms_threshold": 10
            }
        }
    ]
}

HTTP 429 Too Many Requests (Rate Limit Exceeded)¶

This error is returned when the rate of requests exceeds the allowed limit of 1000 requests per minute per IP.

Best Practice for Rate Limit Handling

When implementing retries for rate-limited requests:

Use exponential backoff: Start with a base delay (e.g., 1 second) and double it after each retry
Add jitter: Include random variation (±20%) to the delay to prevent thundering herd problems

Example implementation:

import random
import time
def get_retry_delay(attempt, base_delay=1, max_delay=60):
    # Calculate exponential backoff
    delay = min(base_delay * (2 ** attempt), max_delay)
    # Add jitter (±20%)
    jitter = delay * 0.2
    return delay + random.uniform(-jitter, jitter)

This approach helps distribute retry attempts and prevents overwhelming the API when rate limits are hit.