Integration Best Practices

1. Authentication and session handling

Use the login endpoint to get a JWT and include it in the Authorization: Bearer <token> header for all the requests. Store the token securely (never in client-side code), remove it when logging out, refresh/re-authenticate once on 401 before retrying the request, and use the whoAmI endpoint to verify the active user identity when required.

2. Required headers and time awareness

Set the content type to application/json for all requests and responses. For core functionality, include the X-Timezone header with a valid IANA value such as America/Los_Angeles. This lets AcuView process time-sensitive operations and present dates and datetimes consistently across records and history views. If validation fails for the time zone, the API responds with a 400 error and a ProblemDetails body indicating that the time zone must be a valid IANA or Windows identifier.

3. Error handling with ProblemDetails

AcuView uses a consistent ProblemDetails schema for errors. Parse title, status, detail, and instance to drive user messaging and logs. Map errors to actions: re-authenticate on 401, request different permissions for 403, fix inputs for 400, and apply a measured retry for 500. Do not retry validation errors. When a field-level validation fails (for example, an invalid time zone), surface the exact message from the errors object to the operator. Keep a limit on automatic retries and add backoff so you do not generate new failures while the system recovers.

4. Pagination and retrieval strategy

The loan listing endpoint supports page, pageSize, sorting, and multiple filters. Use a modest page size during initial rollout to keep payloads small and latency predictable, then increase as you prove capacity. Drive navigation using the pageNumber, totalPages, and hasNext flags that come back in the response. When exporting many records, iterate page by page and persist your progress so partial exports can resume. Prefer server-side filters (date range, status, amount) over client-side filtering to reduce bandwidth and processing time.

5. Input validation before sending

Validate data at the edge of your system so only clean payloads reach AcuView. Follow the documented formats: dates as YYYY-MM-DD, timestamps as ISO 8601, numbers without currency symbols, and enumerations that match the platform (for example, loan statuses of Pending, Approved, Denied, WrittenOff, and PaidOff; account-verification results of Match, Warning, and NotFound). Normalize phone numbers and emails to a consistent pattern and strip formatting artifacts from numeric fields like income and requested amounts. Where you collect bank account numbers and routing numbers, validate length and character set before transmission.

6. Security and handling of sensitive data

Treat personally identifiable information as sensitive at every step. Do not log full SSNs, bank account numbers, or passwords. When you must store identifiers for later reference, keep only masked forms such as ssnLast4 or bankAccountNumberLast4. Use HTTPS end to end and encrypt sensitive data at rest. Limit access via application roles; the roles array in whoAmI helps confirm that a session has the right privileges for the operation you are performing. Rotate credentials and session keys as part of your standard operations, and scope access to just the AcuView operations your application requires.

7. Rate limiting and request shaping

Design the client to send a steady, predictable stream of calls rather than bursts. Add concurrency limits in your integration layer and apply exponential backoff with jitter on transient errors. Queue batch work such as large record searches or history pulls, and spread that work across quieter periods of the day. Favor incremental reads using filters (for example, by date window or status) so you only fetch what changed.

8. Monitoring, logging, and traceability

Capture the HTTP status, endpoint, elapsed time, instance path from ProblemDetails, and a correlation or request ID if present in your logs. Add your own correlation ID to outbound requests so you can tie application events to API calls and user actions. Alert on rising 4xx rates for the same endpoint (indicates a validation or contract drift) and on any spike in 5xx responses. Use whoAmI checks in health probes for environments that maintain long-lived sessions.

9. Workflow guidance for common operations

For bank account verification, send the holder name, account number, and routing number and evaluate the matchStatus. A status of Match clears the verification step; Warning indicates discrepancies that you should present for manual review; NotFound blocks the workflow until the data is corrected. For loan creation and checks, submit the borrower profile and requested amount, then read recordVerification, recordInformation, and any analysis fields to update your internal decision state. When updating a loan, send only the fields required by the application-management endpoint and confirm the summary and per-record messages that come back.

10. Data minimization and lifecycle

Only request and transmit the fields needed for the workflow you are running. Keep retention windows tight for raw PII and delete transient payloads when the operation has completed. Where you need reporting, persist derived or aggregated forms rather than full originals. If you export records for analysis, mask PII and replace unique identifiers with reversible tokens stored in a secure vault.

11. Consistent environments and testing

Use fixed test inputs and known time zones during integration and QA so you can reproduce outcomes. Record representative responses from verifyBankAccount, LoanRecord/check, LoanRecord/{id}, and loan-history and build contract tests that validate field presence and type. Add negative tests that expect the documented 400 validation body and the 401/403 flows. Keep a small rotating set of live queries to verify production behavior without creating unnecessary load.