Integration Best Practices
1. Authentication and Session Management
Authentication and session management are central to securing your integration with
the AcuCheck API. It is recommended that all API calls be made server-to-server,
keeping keys and tokens strictly on the server side. Always use HTTPS to protect
credentials in transit, and never expose API keys or session tokens in client-side
applications. AcuCheck supports multiple authentication methods including API keys
and JWT bearer tokens. API keys should be placed in the request header under
X-Api-Key, while JWT tokens should be passed using the
Authorization: Bearer {token} header after obtaining them
through the login endpoint. Session management should incorporate token refresh and
revocation processes, such as using the logout endpoint to terminate sessions and
the status endpoint to validate ongoing sessions. By handling tokens securely and
validating them regularly, you ensure that your integration remains resilient
against unauthorized access.
2. Request Hygiene and Data Validation
Each request sent to the API should be clean, validated, and minimal. Validating inputs such as email addresses, phone numbers, social security numbers, and routing numbers before submission reduces errors and enhances the user experience. Applications should avoid over-posting by sending only the data necessary for the intended transaction, minimizing exposure of sensitive fields. Consistency in data formatting is equally important: timestamps should follow ISO 8601 in UTC, and identifiers should be treated as opaque values rather than parsed. This consistent validation and hygiene safeguard both performance and compliance.
3. Pagination, Filtering, and Sorting
To handle large data sets effectively, AcuCheck APIs provide pagination, filtering,
and sorting options. Developers should use parameters such as
pageNumber, pageSize,
orderBy, and order to control data retrieval. Page
sizes should be chosen carefully values between 25 and 50 work well for most
dashboards, while higher limits can be used for data exports. API responses also
include metadata such as totalRecords, pageNumber,
and pageSize, which can be used to manage user interfaces for
navigation. Applying filters, such as by customer type, name, or report status,
ensures that only relevant results are retrieved, optimizing both performance and
clarity.
4. Error Handling and Retries
Error handling in AcuCheck integrations should always account for both HTTP-level and
logical errors indicated in the response. Every response includes a
success field and a message string, along with
potential error arrays. Applications should distinguish between client errors, such
as validation issues (400), and server errors (500), and respond appropriately. For
transient issues, such as timeouts or internal errors, implement retry logic with
exponential backoff and jitter to avoid overwhelming the server. Logging should
capture details like endpoints, correlation IDs, HTTP statuses, and messages,
enabling faster troubleshooting and monitoring of recurring issues.
5. Idempotency and Safe Mutations
When dealing with customer creation, report requests, or any actions that might be retried due to network or client issues, idempotency is essential. Without safeguards, duplicate actions may occur, such as multiple report requests for the same customer. To prevent this, applications should generate their own idempotency keys and include them in POST requests. On the server side, deduplication logic can ensure that repeated actions do not create duplicate records. Checking the current status of a resource before performing updates or resubmissions further reduces duplication and ensures cleaner transaction flows.
6. Financial Data Flows (Instant Bank Analysis)
The typical workflow for financial data analysis involves creating or locating a
customer, generating a report request, polling until the report is completed, and
finally retrieving account and transaction details. It is important to adhere to the
defined status values such as Pending, Completed, Expired, or Failed, and to respect
the communication channels defined by the sendVia parameter.
Polling intervals should not be aggressive; instead, a reasonable cadence such as
every 30 to 60 seconds should be used to check the status of reports. By respecting
these workflows and pacing, integrations remain both efficient and
user-friendly.
7. PII and Security Controls
Since AcuCheck handles sensitive financial and personal information, strict security practices are required. Personally Identifiable Information (PII), including SSNs and bank account numbers, should never be logged or displayed in plain form. Masking values in logs, encrypting data at rest, and limiting access by user roles are all necessary practices. Bearer tokens and refresh tokens must be stored securely on servers rather than in client-side storage, with proper rotation schedules. Additionally, compliance with data retention rules ensures that sensitive information is not kept longer than required, reducing exposure risk.
8. Concurrency and Rate Usage
429 Too Many
Requests9. Versioning and Change Safety
API integrations should always be designed to tolerate changes. Treat endpoints, response structures, and fields as contracts while still being prepared to ignore newly introduced fields. Parsing logic should not break when encountering unexpected nulls or additional fields. A lightweight contract test run periodically against non-production environments can help detect changes in response formats early, providing time to adjust integrations before they affect production systems.
10. Observability and Audit
Observability ensures that integrations are transparent and traceable. Each API call should be logged with structured information including the endpoint, method, status, latency, and outcome. Correlation IDs can be generated and passed across services to trace transactions through distributed systems. For auditing, integrations should record whether actions were triggered manually by users or automatically by the system. This provides accountability, useful for compliance, and essential during investigations or audits.
11. Widget and Embedded Flows
If the widget-based integration approach is used, developers must validate tokens before initializing the widget. Proper handling of callbacks ensures smooth navigation during both success and failure scenarios. If a widget fails to load or the session has expired, fallback mechanisms must be available to guide the user to alternate workflows. Providing retry options or redirecting users to support channels enhances resilience and maintains trust in the integration. Thorough testing of widget behaviors across browsers and devices further ensures reliability.
12. Testing Strategy
Testing should extend beyond happy-path scenarios. Unit tests should validate request construction and response parsing, while integration tests should simulate complete workflows from customer creation to report retrieval. Negative testing is equally important to validate that the integration handles authentication failures, validation errors, missing resources, and server failures correctly. Load testing with paginated endpoints provides insight into how the system performs under scale and helps fine-tune concurrency and rate controls.
13. Practical Examples
Practical examples help anchor these practices into real-world workflows. For instance, after authenticating through the login endpoint and obtaining a bearer token, a customer may be created with validated input fields. A report request can then be generated for the customer, and the integration can poll the report requests endpoint until the report status becomes Completed. The final financial report can then be retrieved, parsed, and displayed. Similarly, when working with lists, integrations should start with moderate page sizes, check total record counts, and provide navigation controls in user interfaces for a seamless experience.
14. Quick Checklist
To simplify adherence, a quick checklist can be followed: always secure API communications over HTTPS, validate inputs, apply pagination, and handle errors comprehensively. Retry logic should be limited to transient failures, sensitive information should be masked and encrypted, and polling should be spaced out responsibly. Response parsing must tolerate unknown fields, contract tests should be run regularly, and widget integrations should include robust fallback mechanisms. Following this checklist keeps the integration aligned with security, performance, and reliability standards.