Validation

The Embrace platform performs automatic validation during quote submission (e.g., email format, name length, address plausibility). For improved UX you can pre‑validate user inputs with dedicated endpoints prior to calling the main quote API.

Use these endpoints to provide immediate feedback and reduce failed quote attempts. They do not create or modify quotes directly.

Validate Address

POST /v2/validation/address

Endpoint reference: Validate Address Endpoint

Request Body

{
  "address": {
    "line1": "123 Main St.",
    "line2": "string",
    "city": "Cleveland",
    "state": "OH",
    "zipCode": "44120"
  }
}

Response

Returns a standardized/normalized address plus validation indicators.

{
  "standardizedAddress": {
    "line1": "123 Main St.",
    "line2": "string",
    "city": "Cleveland",
    "state": "OH",
    "zipCode": "44120"
  },
  "isAddressValid": true,
  "validationMessages": ["string"]
}

Field Notes

  • standardizedAddress: Canonical casing & abbreviations suitable for displaying back to the user or storing.
  • isAddressValid: Boolean summary indicator. Treat false as a soft failure—allow user correction.
  • validationMessages: Zero or more human-readable strings explaining issues or adjustments.

Typical Flow

  1. User enters address form fields.
  2. Front end sends request to your backend proxy (never expose subscription key client-side).
  3. Backend forwards to Embrace validation endpoint.
  4. Display standardized result (and optionally allow the user to accept/reject suggested changes) before quoting.

Backend Example (Minimal C#)

app.MapPost("/validate-address", async (ValidateAddressEnvelope envelope, HttpClient http, IConfiguration cfg) =>
{
    var upstream = new HttpRequestMessage(HttpMethod.Post, "https://[embrace-test-endpoint]/v2/validation/address")
    {
        Content = new StringContent(System.Text.Json.JsonSerializer.Serialize(envelope), System.Text.Encoding.UTF8, "application/json")
    };
    upstream.Headers.Add("epi-apim-subscription-key", cfg["EMBRACE_API_KEY"]);
    var resp = await http.SendAsync(upstream);
    var payload = await resp.Content.ReadAsStringAsync();
    return Results.Content(payload, "application/json", resp.StatusCode);
});

public record ValidateAddressEnvelope(Address address);
public record Address(string line1, string? line2, string city, string state, string zipCode);

UI Recommendations

  • Disable the Quote / Continue button until either validation succeeds or the user explicitly overrides with a confirmation.
  • Autofill corrected casing (e.g., CLEVELAND -> Cleveland) from standardizedAddress.
  • Show inline messages for each element of validationMessages.
  • Cache successful validations temporarily (e.g., 5–10 minutes) to avoid duplicate calls if the user navigates back/forward.

Error Handling

  • Treat non-2xx responses as transient failures; allow retry.
  • Time out requests reasonably (e.g., 5 seconds) and surface a generic fallback message.
  • Log the original user-entered address alongside standardized result for auditing.

Validate Name

POST /v2/validation/name

Endpoint reference: Validate Name Endpoint

Use this to standardize capitalization and screen for obviously invalid name inputs prior to quoting.

Request Body

{
  "firstName": "string",
  "lastName": "string"
}

Response (Representative)

While the exact schema may evolve, you can expect a structure that echoes standardized values and any validation messages. Always consult the live schema for authoritative fields.

{
  "standardizedFirstName": "String",
  "standardizedLastName": "String",
  "isNameValid": true,
  "validationMessages": ["string"]
}

Typical Uses

  • Normalize user input (e.g., jOhN -> John).
  • Detect placeholder or garbage names (returning messages for UI prompts).
  • Provide immediate inline feedback before continuing to pet details.

Backend Example (Minimal C#)

app.MapPost("/validate-name", async (NameRequest name, HttpClient http, IConfiguration cfg) =>
{
    var upstream = new HttpRequestMessage(HttpMethod.Post, "https://[embrace-test-endpoint]/v2/validation/name")
    {
        Content = new StringContent(System.Text.Json.JsonSerializer.Serialize(name), System.Text.Encoding.UTF8, "application/json")
    };
    upstream.Headers.Add("epi-apim-subscription-key", cfg["EMBRACE_API_KEY"]);
    var resp = await http.SendAsync(upstream);
    var payload = await resp.Content.ReadAsStringAsync();
    return Results.Content(payload, "application/json", resp.StatusCode);
});

public record NameRequest(string FirstName, string LastName);

Considerations

  • Do not auto-rewrite user-visible fields silently; show standardized suggestion if it differs materially.
  • Treat isNameValid=false as a prompt for correction rather than a hard blocker unless business rules require.
  • Combine with address validation to reduce multi-step friction.

Validate Phone

POST /v2/validation/phone

Endpoint reference: Validate Phone Endpoint

Standardizes and validates a phone number (format, length, characters) prior to quoting or contact persistence.

Request Body

{
  "phoneNumber": "string"
}

Response

{
  "standardizedPhoneNumber": "string",
  "isPhoneNumberValid": true,
  "validationMessages": ["string"]
}

Typical Uses

  • Normalize user-entered formats ((555) 123-4567 -> 5551234567 or canonical display form).
  • Provide immediate feedback for incomplete or malformed numbers.
  • Prevent unnecessary quote attempts with invalid contact info.

Backend Example (Minimal C#)

app.MapPost("/validate-phone", async (PhoneRequest phone, HttpClient http, IConfiguration cfg) =>
{
    var upstream = new HttpRequestMessage(HttpMethod.Post, "https://[embrace-test-endpoint]/v2/validation/phone")
    {
        Content = new StringContent(System.Text.Json.JsonSerializer.Serialize(phone), System.Text.Encoding.UTF8, "application/json")
    };
    upstream.Headers.Add("epi-apim-subscription-key", cfg["EMBRACE_API_KEY"]);
    var resp = await http.SendAsync(upstream);
    var payload = await resp.Content.ReadAsStringAsync();
    return Results.Content(payload, "application/json", resp.StatusCode);
});

public record PhoneRequest(string PhoneNumber);

Considerations

  • Preserve the raw user input separately if you need to show their original formatting alongside standardized output.
  • Use validationMessages to highlight country/length issues or disallowed characters.
  • Combine with name & address validation for a streamlined pre-quote verification step.

More validation endpoints (Email) will be documented here in future updates.