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

GET

URL

https://app.onramp.us/api/widget/data

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

org_id

Yes

Your Org ID.

email

Yes

The email of an active customer user in your organization who is a member of an active project.

fast_pass

No

Pass 1 to get FastPass auto-login links. This works only when FastPass Auto-Login is turned on in your widget settings. Otherwise you get regular links.

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

project_link

A link to the project in your customer portal.

start_date, end_date

Strings in YYYY-MM-DD HH:mm:ss format. If the project has no start or end date set, the field is the string None, so check for it before you parse the date.

percent_complete

Always a string. Cast it to a number if you need one.

days_remaining

Always a string. It's negative once the end date has passed, and 0 when the project has no end date.

Errors

Every error returns 400, with "success": false and "data": null. The message tells you the cause.

message

Cause

There is a problem with the args passed

org_id or email is missing.

There is a problem with the email address

The email isn't formatted correctly.

There is a problem with the organization uuid

org_id isn't a valid ID.

There is a problem with the org_id

The organization isn't found or is disabled.

There is a problem with the customer

No active customer user with that email exists in your organization.

There is a problem with the project

The customer user isn't on an active project.

widget data could not be retrieved.

Something else went wrong while building the response.

More in Webhooks, APIs & Custom Integrations