This document answers common questions from development and product teams about implementing the Reach API Spec. It covers both technical and process-related topics to help clarify expectations and avoid confusion during integration.
Q: Who defines the spec? Can we modify it?
A: The spec is defined and maintained by Reach. Partners should not make changes to the structure, endpoints, or fields. If you believe the spec should evolve to support a new use case, Reach is open to feedback and can consider it for future versions.
Q: What kind of data is required to make this integration work?
A: Partners must provide company-level actuals data. If your organization uses classes or departments actuals must be provided at that level as well. Aggregated data alone is not sufficient if your reporting or workflow depends on class/department distinctions.
Q: How long does it take to get the integration deployed?
A: Once the API is set up on your side, Reach will conduct tests. If all tests pass, deployment typically takes about one week.
Q: What happens if data is missing or incomplete?
A: Missing or incomplete data may cause errors in integration, incorrect reporting, or workflow failures. Ensure all required fields are populated and reflect the current period before starting integration.
Q: Can we add extra fields to the response?
A: Any extra fields in the response will be ignored. Only the fields defined in the spec are used by Reach.
Q: What kind of data are we exposing?
A: You’re exposing structured, read-only data used for financial reporting — typically including company info, chart of accounts, and time-based account values.
Q: How much does it cost?
A: Pricing depends on your use case. Contact Arthur at arthur@reachreporting.com for details.
Q: Do we need to support POST requests or any write operations?
A: No. The integration is read-only. While some POST requests exist, they do not perform any write operations.
Q: What format should responses be in?
A: All API responses must be returned in valid JSON with the correct content type (application/json), including errors.
Exception: The OAuth token endpoint follows the OAuth 2.0 spec and returns a form-encoded response (application/x-www-form-urlencoded).
Q: How are actuals provided?
A: Actuals should be returned from financial statements when the budget ID is blank. These records represent the company-level actuals used by Reach. If Class Id and Department Id are blank, then the unfiltered company actuals should be returned.
Q: Do we need to support OAuth?
A: Yes. OAuth is the required authentication method. Reach will request access tokens scoped to specific customers, and your API must validate and authorize those tokens for each request.
Q: Is HTTPS required?
A: Yes. Your API must be accessible via HTTPS with TLS 1.2 or higher (TLS 1.3 recommended).
Q: How often does Reach sync?
A: Reach typically syncs overnight (during off-hours), and customers can also trigger manual syncs. Daily volume is reasonable and capped per customer.
Q: Who controls when data is refreshed?
A: The customer can initiate a sync at any time (within limits), and Reach will also schedule background syncs. Your API just needs to be available when called.
Q: Do we need to notify Reach when data changes?
A: No — the current integration is pull-based. Reach will call your API on a schedule. Future versions may support webhooks or push-based syncing.
Q: What should we do before going live?
A: Complete the Developer Checklist, test with real data, and send Reach your base API URL and test OAuth credentials.
Q: Who handles support if something goes wrong?
A: If the issue is on your side (e.g., incorrect data or access issues), your team is responsible. If it's related to how the data is displayed or reported in Reach, the Reach team will handle it.
Q: Will Reach let us know if a sync fails?
A: Yes. Reach monitors sync jobs and will surface errors or reach out if recurring issues are detected.