This API verifies whether an Iranian national code matches a given Gregorian birth date. A successful inquiry deducts the service tariff from the caller's wallet and returns identity attributes such as serial, name, and registry office information.
POST/api/services/national-code-birthday-match/
نیاز به احراز هویت
Token
100 requests/minute
مستندات
Overview
Overview
The National Code Birthday Match API verifies whether an Iranian national code belongs to the person born on a specific Gregorian date. This service is useful for identity verification, fraud prevention, and customer onboarding flows.
On each successful call, the service:
Validates the national code format
Validates the Gregorian birth date format
Checks the match via Sepal Yar
Returns identity information such as first name, last name, and serial
Deducts the service tariff from the wallet
Returns a unique request reference for audit purposes
Authentication
Authentication
This API requires token-based authentication plus a unique code header.
Retrieve your API token and unique code from the admin panel.
Birth date must be supplied in the Gregorian calendar. Convert Jalali dates to Gregorian before sending the request.
Response Format
Response Format
Successful responses include the following fields:
success: Boolean flag indicating success
request_ref: Unique reference for the request
amount: Charged amount (in Rials)
response_data: Matching result and identity fields
response_time_ms: Upstream response time
error_message: Null for successful calls
On failure, the response contains success: false and an error object with details.
Error Handling
Error Handling
The API uses standard HTTP status codes:
200 OK: Request processed successfully
400 Bad Request: Invalid or missing parameters
401 Unauthorized: Missing or invalid authentication headers
402 Payment Required: Insufficient wallet balance
502 Bad Gateway: Sepal Yar service error
Always inspect the error.details field when present to identify validation errors returned by the platform.
Best Practices
Best Practices
Validate national code and convert dates to Gregorian before sending requests.
Log and store the returned request_ref for traceability.
Handle validation errors gracefully and surface details to clients.
Monitor wallet balance to avoid 402 responses.
Use exponential backoff for transient 5xx errors.
پارامترهای درخواست
پارامتر
نوع
اجباری
توضیحات
مثال
national_code
String
اجباری
Iranian national code (10 digits). Only numeric characters are allowed.
اعتبارسنجی: Must be exactly 10 digits. Numbers only.
1234567890
birth_date
String
اجباری
Gregorian birth date in YYYY-MM-DD format. Shamsi dates must be converted to Gregorian before calling the API.
اعتبارسنجی: Must follow YYYY-MM-DD format. Gregorian calendar.
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Token YOUR_AUTH_TOKEN");
client.DefaultRequestHeaders.Add("X-Unique-Code", "YOUR_UNIQUE_CODE");
var payload = new
{
national_code = "1234567890",
birth_date = "2001-04-21"
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://inquiry.sepal.ir/api/services/national-code-birthday-match/",
content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
