Records

Records represent data retrieved directly from official sources — such as social security agencies and government registries — by querying those sources on behalf of your users. Unlike Accounts, which rely on the user connecting their own credentials through the Wink Widget, or Archives, which rely on the user uploading their own documents, Records are created by your application submitting identifying information (such as name, mobile number, ID numbers, or email address) along with the user's consent. Smile then queries the relevant source organization and returns a structured result.

This makes Records particularly suited to workflows where you need to verify or enrich user-provided information against authoritative third-party sources, without requiring the user to have an active account with that source or to upload anything themselves.

How Records Work

All Records APIs follow the same asynchronous request-then-poll pattern:

1. Submit a request. Your application calls the appropriate Records endpoint (e.g., POST /socialSecurities) with the required identifying parameters and the user's consent object. Smile creates a Record object immediately and returns it with a status of PROCESSING.

2. Wait for completion. Smile queries the source organization in the background. This typically completes within approximately one minute, though timing can vary depending on source availability.

3. Receive a webhook notification. When processing finishes, Smile fires a RECORD_COMPLETED webhook event to your registered endpoint. Subscribe to this event to avoid polling.

4. Retrieve the result. Call GET /{recordType}/{id} with the ID returned in step 1, or retrieve the completed record from the webhook payload. Inspect the status and resultCode fields to determine the outcome.

Record Status Values

All Record objects share a common status field that reflects the processing state of the request:

Result Code Values

When status reaches COMPLETED or ERROR, the resultCode field provides the final outcome:

📘

Note

A resultCode of NO_DATA is a valid, non-error outcome. It means the query completed successfully but no record was found at the source for the submitted identifiers. This is distinct from SYSTEM_ERROR or SERVICE_UNAVAILABLE, which indicate that the lookup itself could not be completed.

Consent

All Records requests require a consent object. This captures the user's explicit agreement to have their data queried from the source organization on their behalf. The consent object must include, at minimum, consentedAt (the timestamp when consent was given) and consentedWith (a human-readable statement of the consent provided).

You may optionally reference a Consent Template created via the Consent Templates API using consentTemplateId.

{
  "type": "Terms And Conditions",
  "version": "1",
  "consentedWith": "I agree to the terms and conditions.",
  "consentedAt": "2021-04-14T09:30:24Z",
  "consentTemplateId": "ct-5b79399a68524234bb0ead472648282d"
}

Templates

Records APIs use template IDs (templateId) to determine which source organization and country to query. Each template corresponds to a specific record source and region. The required input parameters vary by template.

Always pass the correct templateId for the country and record type you intend to query. Passing an incorrect template for the input parameters provided will result in a resultCode of INVALID_PARAMETERS.

Webhooks

RECORD_CREATED

Fired when a Record has been successfully submitted and created in the Smile system.

{
  "id": "et-123abc456def789abc123def456abc78",
  "version": 1,
  "type": "RECORD_CREATED",
  "createdAt": "2021-04-14T09:30:24Z",
  "data": {
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "recordId": "ss-123abc456def789abc123def456abc78",
    "recordType": "SOCIAL_SECURITY"
  }
}

RECORD_COMPLETED

Fired when processing for a Record has finished — whether successfully (SUCCESS), with no data found (NO_DATA), or with an error. Always check the resultCode on the Record object after receiving this event.

{
  "id": "et-123abc456def789abc123def456abc78",
  "version": 1,
  "type": "RECORD_COMPLETED",
  "createdAt": "2021-04-14T09:30:24Z",
  "data": {
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "recordId": "ss-123abc456def789abc123def456abc78",
    "recordType": "SOCIAL_SECURITY"
  }
}

Available Record Types

📘

Note

Additional record types are planned. Contact your Smile account representative for information on upcoming regions and record sources.