Partner workflow: Customer engagement
In this recipe, when we say customers, we are referring to your customers, and not the BILL customer entity.
When your customers onboard to the BILL platform for their Accounts Payable (AP) needs, you can engage with them via email and/or in-product messaging.
In this recipe
In this recipe, you build an API workflow that enables you to gather data about your customers. With this workflow, you retrieve all the BILL organizations enrolled by your customers, and then retrieve all the users (including their email addresses) in a selected organization.
When you sign in as a user, you can get a wide range of data, such as the list of bank accounts (to check whether the customer connected a funding bank account or completed bank account verification) and the list of payments (to check whether the customer made any transaction in the last 30/60/90 days).
Why engage with customers?
By engaging customers at key touch points based on their needs, you can encourage broader use of the BILL capabilities embedded in your application. Here are some reasons for engagement.
- A customer started enrollment, but did not complete enrollment.
- A customer completed enrollment, but did not add a funding bank account for making payments.
- A customer completed enrollment, added a funding bank account, but did not complete their bank account verification.
- A customer has not made a transaction in the last 30/60/90 days.
What you'll build
In this recipe, you create an integration with the BILL v3 API in the sandbox environment.
- Retrieve the list of all BILL organizations enrolled by your customers.
- Retrieve the list of users in a selected organization.
- Sign in as a user of the selected organization.
- Gather funding bank accounts and payments information about your customer.
What you need before you begin
| Prerequisite | Description |
|---|---|
| API basics | A basic understanding of working with API endpoints. |
| Credentials | Your BILL Embed Partner credentials are required for your partner API requests. When you become a BILL embed partner, you get the required credentials (username, password, appKey, and devKey) for testing in the sandbox environment. You will use your devKey only in the final chapters in this recipe. |
Chapter 1: Partner API login
In this chapter, you complete partner login with the API.
To begin, enter your API login credentials in the fields below. See the What you need before you begin section in this recipe if you have not set up your credentials.
https://gateway.stage.bill.com/connecthttps://gateway.prod.bill.com/connectComplete the partner login with POST /v3/partner/login. Simply click Send to get a 200 OK response.
In the response, a new partner login sessionId is available. You use this sessionId and your appKey in the next set of chapters.
Chapter 2: Get list of organizations
In this chapter, you get details about BILL organizations that belong to your customers.
The ?sort=createdTime:desc query parameter enables you to sort BILL organizations in the descending order based on createdTime. Click Send to get a 200 OK response.
In the response, you get a list of BILL organizations enrolled by your customers based on the filter and sort query parameters. You can identify each organization by the organization id in the response.
In Chapter 3, we use the id of the first organization in the response.
Chapter 3: Get list of users
In this chapter, you get the list of users in a selected organization. Click Send to get a 200 OK response.
In this example request, we use the id of the first organization returned from the GET /v3/partner/organizations response in Chapter 2.
In the response, you get a list of users in the given organization. You can identify each user by the user id in the response. In addition, the email field provides the email address of each user in the given organization.
In Chapter 4, we use the id of the first user from this response.
Chapter 4: API sign in as user
In this chapter, you are now ready to sign in as the user of your selected BILL organization. Click Send to get a 200 OK response.
In this example request, we are using the id of the first user returned from the GET /v3/partner/users response in Chapter 3.
Congratulations! You are now signed in as the user of a BILL organization. In the response, a new sessionId is available. You use this sessionId along with your devKey in all subsequent BILL v3 API requests for that organization. For example, get the list of bank accounts with GET /v3/funding-accounts/banks or get the list of payments with GET /v3/payments.
Chapter 5: Get list of bank accounts
In this chapter, you get a list of funding bank accounts connected by your customer for making payments. This is an example of an API request that you can make after you have successfully signed in as the user of the BILL organization. Click Send to get a 200 OK response.
Enter your devKey for Chapters 5 and 6.
In the response, you get the complete list of funding bank accounts connected by your customer.
If this list is empty, you know that the customer did not connect a funding bank account. You can send the customer an email about completing their enrollment.
In addition, if the customer does not have a verified funding bank account ("status": "NOT_VERIFIED"), the customer is not ready to make payments. You can send the customer an email about completing their bank account verification.
Chapter 6: Get list of payments
In this chapter, you get a list of payments made in your selected BILL organization. This is an example of an API request that you can make after you have successfully signed in as the user of the BILL organization. Click Send to get a 200 OK response.
In the request, you add a sort query parameter in the GET operation to sort all payments in the descending order based on createdTime.
In the response, you get a list of payments made by your customer. You can further customize your GET /v3/payments request with filtering and sorting capabilities.
If the createdTime value is over 30 days old, you know that the customer has not made a payment for at least 30 days. You can send the customer an email about making payments.
What you learned in this recipe
You just completed the BILL Embed Partner workflow to retrieve customer-specific information that can help you engage with your customers more effectively.
- Complete the partner API login and create a session.
- Retrieve a list of all BILL organizations enrolled by your customers.
- Retrieve the list of users (and their email addresses) in a selected organization.
- Sign in as a user of the selected organization.
- Gather more usage data, such as funding bank accounts and payments.
With this information, you can curate email engagement campaigns for a range of reasons.
- Prompt customers to complete enrollment.
- Prompt enrolled customers to make their first payment.
- Prompt paying customers to deepen their payment volume and/or to explore incremental features.
Updated about 15 hours ago