Widget API reference
Updated
These tables cover the Widget API: the endpoint, its query parameters, the responses it returns and what each error means. The Widget API returns live project data for one customer user as JSON.
Find your Org ID
The Widget API needs your Org ID. To find it, go to Settings > Embed widget, under API & webhooks, and open the API Data tab. Query Parameters shows your org_id already filled in, along with your own email.
The API Data tab also shows the full endpoint URL, filled in with your Org ID and your own email. Select Try it out to open that request in a new browser tab. Your own email doesn't belong to a customer user, so that request returns There is a problem with the customer. To see project data, replace the email in the URL with the email of an active customer user in your organization.
You can also find the Org ID on the Embed tab: select Script, and the Org ID is in the snippet.
Endpoint
Item | Value |
|---|---|
Method |
|
URL |
|
Example request:
https://app.onramp.us/api/widget/data?org_id=YOUR_ORG_ID&email=customer@example.com
Query parameters
Parameter | Required | What it takes |
|---|---|---|
| Yes | Your Org ID. |
| Yes | The email of an active customer user in your organization who is a member of an active project. |
| No | Pass |
To learn what FastPass Auto-Login does and what to check before you turn it on, see Embed the customer portal in another application.
Responses
A valid request returns 200 with JSON. An invalid request returns a 400 error.
The shape of a successful response depends on how many active projects the customer user is on.
One active project
{
"status": 200,
"success": true,
"message": "widget data",
"data": {
"email": "customer@example.com",
"org_id": "ef7209a4-600d-46d2-bbd6-c41128513100",
"customer_logo": "https://app.onramp.us/static/img/logos/cb9cca9d.png",
"project_link": "https://customer.onramp.us/portal/v3/app/project/WYxk8mepY2aMyJNj",
"project_name": "Acme Onboarding",
"start_date": "2023-07-12 00:03:00",
"end_date": "2023-08-13 00:03:00",
"percent_complete": "0",
"days_remaining": "32"
}
}
More than one active project
There's no top-level project_link. Instead, data has project_count, a portal_link to the customer portal, and a projects array. Each entry carries its own link, name, dates and progress.
{
"status": 200,
"success": true,
"message": "widget data",
"data": {
"email": "customer@example.com",
"org_id": "ef7209a4-600d-46d2-bbd6-c41128513100",
"customer_logo": "https://app.onramp.us/static/img/logos/cb9cca9d.png",
"project_count": 2,
"portal_link": "https://customer.onramp.us/portal/",
"projects": [
{
"project_link": "https://customer.onramp.us/portal/v3/app/project/WYxk8mepY2aMyJNj",
"project_name": "Project Alpha",
"start_date": "2023-03-12 00:03:00",
"end_date": "2023-04-01 00:03:00",
"percent_complete": "42",
"days_remaining": "10"
}
]
}
}
With fast_pass=1 and FastPass Auto-Login turned on, portal_link is the auto-login link and each project's project_link stays a regular link.
Response fields
Field | What it holds |
|---|---|
| A link to the project in your customer portal. |
| Strings in |
| Always a string. Cast it to a number if you need one. |
| Always a string. It's negative once the end date has passed, and |
Errors
Every error returns 400, with "success": false and "data": null. The message tells you the cause.
| Cause |
|---|---|
|
|
| The email isn't formatted correctly. |
|
|
| The organization isn't found or is disabled. |
| No active customer user with that email exists in your organization. |
| The customer user isn't on an active project. |
| Something else went wrong while building the response. |