Skip to main content

How to Generate a Customer Portal URL via API

Francisco Munoz
  • Updated

Our API allows you to programmatically perform functions and operations outside of the Upflow UI, such as creating or updating a new customer, invoice, customer contact, etc.

In this case, you will be using the Create Portal URL endpoint to generate a Customer Portal URL (for a single customer per request) with a customized validity timeframe. Currently, URL's delivered via invoice reminders and generated on the customer page have a default lifespan of 25 days.

The steps involved are outlined below:
1. You can use a free API testing tool such as Postman to run this request.
2. The URL for the request is: 

https://api.upflow.io/v1/customers/customerId/portal

*If you're testing on an Upflow sandbox environment, the URL differs slightly:

https://api.sandbox.upflow.io/v1/customers/customerId/portal

You can fetch the customerId by accessing the respective customer's page and grabbing the value to the immediate right of '/customers':

So the URL for the request would be formatted as such:

https://api.upflow.io/v1/customers/a123b456-c7d8-4fb3-a3ae-29fd1b4a287e/portal

You can also use the External Id set for that customer entity instead, which will be the customer internal id for any organizations or accounts synced with a native integration.
In the following example the External Id is the Netsuite Internal ID:

So the URL for the request would be formatted as such:

https://api.upflow.io/v1/customers/external:123/portal

3. The Upflow API uses API keys to authenticate requests. You can view your API keys by accessing your Account Settings > under Apps > click on API. 

Once you have these API keys, you can enter them in your request under Headers:

* The third header is Content-Type:application/json.
(By specifying this header, we ensure that the server knows to interpret the data correctly as JSON, which helps it process and respond accurately to the request)

4. In the Body of the request, you will specify the data format for the request as Raw / JSON. The JSON array will consist of the following:

  • "frameAncestors"
    To embed it in an iframe to allow your users to access the customer portal from your app, you must specify this attribute in the request. It will contain space-separated fully qualified domain names which are authorized to embed the portal in an iframe.
    (Leave it out altogether if you don't intend to use the URL for this purpose.)
    Example:
"frameAncestors": "extranet.merchant.com intranet.merchant.com"
  • "expiresIn"
    Expressed in seconds. Time span during which the token is valid. Default is 86400 (1 day)
    Example:
"expiresIn": 86400

So, if you're only looking to generate a Customer Portal URL with an expanded lifespan (two months in this case), the Request Body will look like the following: 

{
"expiresIn": 5184000
}

5. This is a POST endpoint, so make sure that's specified in the request.

6. Now, you're ready to run this POST request!
The response will contain the URL for the Customer Portal which you can then provide to your customer:

FAQ

  • What is the default lifespan for the request if I don't specify or include the "expiresin" attribute?
    24 hours.

Related to

Related articles