Asynchrounous API
The Onboarding and Reporting endpoints are asynchronous, due to the nature of Fonoa’s interactions with 3rd party systems like tax authorities. Though most requests only take a few seconds, some may take longer.
Our API currently supports polling. Webhook support is on the roadmap.
Jobs
When onboarding an entity or reporting a transaction, a job is created. This job represents the status of the request in our system. If the execution fails for whatever reason, the job will fail and a list of errors will be returned explaining how to address the issue. If it is successful, it will indicate the location of the onboarded entity or transaction where the full details can be fetched.
Polling
When polling a job for status, we recommend separating requests by a minimum of 1 second and retrying with exponential backoff, as some requests may be slow, e.g. if a tax authority API is not responding.
Errors
When a request fails, a list of errors is provided. The error object contains a human-readable code, a type outlining the source of the error (e.g. Fonoa validation error, tax authority error), and a message explaining how to address the issue. When possible the field position is provided, giving the exact location of the erroneous data point.
“errors”: [
{
"code": "tax_amount_incorrect",
"type": "validation",
"message": "The tax amount provided is above the 2 cents tolerance threshold. Expected amount: $1.42",
"field": "items[4].tax_breakdown[0].amount"
}
]
Search for onboarded entities and individuals
You can search for onboarded entities and individuals via either Fonoa ID or the external ID that you associate with each onboarding.
The endpoints are both GET and will have the following format:
- https://{{baseurl}}/onboarding/v2/companies/{{id}}
- https://{{baseurl}}/onboarding/v2/individuals/{{id}}
If you are searching by external_id then it is also required to add ?external-id=true to the URL.
the {{baseurl}} is either the demo or prod URL endpoint base: