Forge Customer Portals enable platforms and marketplaces to provide sub account users with self-service onboarding and account management. Each sub account represents a customer or business created and managed through the Forge Dashboard or API. Customer Portals support brand customization and flexible feature configurations while maintaining secure, session-based access.
Accessing the Customer Portal
Platforms can direct their users to Customer Portals by using EasyPost’s POST /customer_portal/account)link endpoint. This session-based URL can be embedded into a platform’s interface or delivered directly to sub accounts for onboarding or account management purposes.
Parameters
These are the parameters that will be needed when calling the POST /customer_portal/account_link endpoint.
session_type enum (required)
Type of Customer Portal session. Options include:
-
account_onboarding: Used to onboard a sub account. -
account_management: Used to manage an existing sub account.
user_id string (required)
The User ID of the sub account for which the portal session is being created.
refresh_url string (required)
The URL to which the sub account will be redirected if the session URL is expired, reused, or otherwise invalid. This should trigger a new session request.
return_url string (required)
The URL to which the sub account will be redirected after exiting the Customer Portal session. This does not confirm completion of the flow; webhook or API polling is recommended for confirmation.
metadata object (optional)
Used to configure the Customer Portal session. Accepted values depend on the session_type:
-
Onboarding: use the
fieldsobject to pre-fill sub account information. -
Management: use the
targetkey to direct the user to a specific portal section.
link string (returned)
The one-time-use session URL returned by the API. Must be used within five minutes. This is the link to which the sub account is redirected to access the Customer Portal.
object string (returned)
Always “CustomerPortalAccountLink”.
created_at timestamp
Timestamp indicating when the session URL was generated.
expires_at timestamp
Timestamp indicating when the session URL will expire.
Portal Types
Onboarding Portal
The Onboarding Portal is a co-branded flow that collects essential contact and address information from sub account users. This portal is optimized for conversion and brand continuity.
Example
curl -X POST https://api.easypost.com/v2/customer_portal/account_link \
-u "EASYPOST_API_KEY": \
-H 'Content-Type: application/json' \
-d '{
"session_type": "account_onboarding",
"user_id": "user_060ab38db3c04ffaa60f262e5781a9be",
"refresh_url": "https://example.com/refresh",
"return_url": "https://example.com/return",
"metadata": {
"fields": {
"name": "Jane Doe",
"email": "jane@example.com"
}
}
}'Metadata for Onboarding
All fields in the metadata object are optional. Only provide fields for which information is available.
If session_type = account_onboarding
"metadata": {
"fields": {
"name": "Jane Doe",
"phone": "8888888888",
"email": "jane@example.com",
"street1": "123 Main St",
"street2": "Apt 4B",
"city": "Austin",
"state": "TX",
"zip": "73301",
"country": "US"
}
}Sub Account Onboarding
Centralized (Child user enabled)
curl -X POST https://api.easypost.com/v2/users \
-u "$EASYPOST_PROD_API_KEY:" \
-H 'Content-Type: application/json' \
-d '{
"user": {
"name": "Child Account Name"
}
}'Decentralized (ReferralCustomer enabled)
curl -X POST https://api.easypost.com/v2/referral_customers \
-u "$EASYPOST_PROD_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"user": {
"name": "Firstname Lastname",
"email": "email@example.com",
"phone_number": "8888888888"
}
}'Account Management Portal
The Account Management portal enables sub accounts to update carrier accounts, manage addresses, view analytics, and perform other administrative tasks. Features can be configured through the Forge Dashboard.
Example
curl -X POST https://api.easypost.com/v2/customer_portal/account_link \
-u "EASYPOST_API_KEY": \
-H 'Content-Type: application/json' \
-d '{
"session_type": "account_management",
"user_id": "user_060ab38db3c04ffaa60f262e5781a9be",
"refresh_url": "https://example.com/refresh",
"return_url": "https://example.com/return",
"metadata": {
"target": "wallet"
}
}'Metadata for Account Management
If session_type = account_management
"metadata": {
"target": "wallet"
} Available targets:
account_settings (default), wallet, carriers, reports, branding, analytics, insurance
Creating a Portal Session
- Send a request to
POST /customer_portal/account_link. - Provide the required parameters:
-
session_type: e.g.,account_onboarding,account_management -
user_id: ID of the sub account -
refresh_url: URL to redirect on session timeout or error -
return_url: URL to redirect after session ends
-
- Retrieve the session URL from the response.
- Redirect the sub account user to the generated URL.
Example
curl -X POST https://api.easypost.com/v2/customer_portal/account_link \
-u "EASYPOST_API_KEY": \
-H 'Content-Type: application/json' \
-d '{
"session_type": "account_management",
"user_id": "user_...",
"refresh_url": "https://example.com/refresh",
"return_url": "https://example.com/return",
"metadata": {"target": "wallet"}
}'
Best Practices
- Customize the portal experience with logos and feature toggles via the Forge Dashboard.
- Monitor portal usage and engagement using reporting tools or vent logs.
FAQs
Q: Can different features be enabled for different sub accounts?
A: Yes. Feature access is configurable per sub account through the Forge Dashboard.
Q: Are Customer Portals secure?
A: Yes. Sessions are authenticated and time-limited, ensuring secure access to sub account data.
Q: Can Customer Portals be embedded in an iframe?
A: Embedding behavior depends on the browser and security settings. It is recommended to open the portal in a new tab or window.