The API Guys

We Integrate Systems

Automatically change Next Action information on Opportunity records

One of the big disagreements I have with Infusionsoft is the use of opportunity records. Infusionsoft wants salespeople to be heavily engaged with opportunity records, constantly updating them, manually moving them through stages and recording what their next action is going to be and when it should take place. I’m not the most sophisticated salesperson, but I just don’t see the point of having to change the opportunity stage AND set the Next Action Date and the Next Action Notes. That’s three actions just to get a reminder to show up two days from now in My Day reminding me to follow up on a proposal I sent.

Instead, I want to cut it down to just one action. (With Stage Moves, I could even cut it down to none, but one thing at a time.) For this example, when I move the opportunity stage to “Proposal Sent”, I want to automatically set the Next Action Date to two days from now at 8:00 am, and I want to set the Next Action Notes to say “Follow up on proposal.”

In Campaign Builder, I’ll start by adding an Opportunity Stage Moved goal, set the goal to the stage I want to trigger from. Then I’ll add a sequence with two HTTP Post snippets.

The first snippet will use Any Date to set the Next Action Date. We need the contactId and App parameters (with our PDev token) to begin with. We’ll set the date to “now”, the time to 8:00 am, and the adjustment to +2 days. The format needs to be the Infusionsoft standard for date/time fields. The saveTo field name we want is “Opportunity.NextActionDate” (no tildes!).

The second snippet will use Any Text to set the Next Action Note. Again we need the contactId and App parameters (with our PDev token). Our textToSave value will be whatever we want to put in the note, and the saveTo value will be “Opportunity.NextActionNotes”.

Now when I mark an opportunity as “Proposal Sent”, the Next Action Date and Next Action Notes will automatically get set as well.

If you want to super-charge this, you can even automate stage moves with our Any Opportunity to Any Stage plugin!

How to set up an HTTP Post in Infusionsoft

HTTP Posts are a way of passing data from one server to another. In order to make our Pocket Developer plugins work, you will need to send data to our server, so that we can tell Infusionsoft what you want done with it.

In Infusionsoft, setting up an HTTP Post is fairly simple. Just go to Campaign Builder, drag out a new sequence or open an existing sequence, and drag the Send HTTP Post snippet from the Process section in the left sidebar.

https://screencast.com/t/O0xUxeQlMh

To configure your HTTP Post, you will need to add a POST URL and add some name/value pairs, also known as parameters.

The POST URL will be the URL of the server where you want to send the data. It may specify a particular directory or script where the code that will catch the data you are sending and interpret it. Any service that asks you to send data via HTTP Post will provide you with the URL where they want you to send the data. For instance, to send data to Pocket Developer’s AnyText plugin, you will use this URL:

http://pocketdeveloper.net/AnyText/

When you create the HTTP Post in Infusionsoft, the first parameter will be filled in by default, with “contactId” as the name, and the merge field for contact Id as the value of the field. You can have as many name/value pairs as you want. If you hover to the right of a parameter, plus and minus buttons will appear; use the plus button to add a parameter, and minus to delete them. For example, if you also want to send the contact’s first name, you might add a parameter with the name “fname” and the value “~Contact.FirstName~”.

The service you are sending the data to will typically provide the names you should use. For instance, to use PDev plugins, in addition to contact Id you must provide your PDev token, so that we know which Infusionsoft application is making the request. This is done by adding a parameter with the name “App” and the value of your PDev token to every HTTP Post to PDev. Our PDev documentation will tell you what other parameters (name/value pairs) to use with each plugin, as well as telling you which ones are required (must be present for the plugin to function) or optional (can be added for convenience and to unlock special features).

Infusionsoft OAuth Flow

OAuth 2 has recently become the web standard for authenticating APIs for use in custom applications.  As a user you have probably seen it any time you try to install an application that works with Facebook, Github or any number of others.  Infusionsoft has adopted the OAuth 2 standard and is slowly pushing us to use it in lieu of the more simple API key authentication. So what is OAuth 2 and how does it work?  And more importantly, how do you set up an Infusionsoft OAuth API connection?

What is OAuth 2?

OAuth 2 is a standard protocol for authentication which can be set up by a web service in order to provide access to their data.  The protocol essentially defines the following 3 types of players or roles which will interact together.

  1. Resource Owner – The resource owner is essentially going to be the end user who will be the one to authenticate the application. For Infusionsoft, this translates to a User in Infusionsoft.  The authentication will ultimately be done by the User or by someone on behalf of the User.
  2. Client – The client is going to be the application that is set up to connect with Infusionsoft in a more generic sense.  The resource owner will essentially be authenticating the client to be able to talk with their Infusionsoft installation.  The client can also have a server which securely stores the resource owner’s access tokens for continual use of the API without the need for re-authentication.
  3. Resource Server/Authentication Server – The resource server is where the user account information is stored, while the authentication server is where the access details are stored in order to for the client to connect with the resource server.  Essentially, Infusionsoft itelf is the resource server, and the OAuth API is the Authentication Server.  From the developers point of view, these are both the same.

How Does It Work?

The OAuth 2 protocol has standard flow, which follows the procedure below:

Abstract Protocol Flow

  1. Developer registers their application (client) with the resource server.  This is usually done with a client_id and client_secret.  Once the developer sets this up, they will use those details to communicate with the resource server in order to set up an authentication process for the user to follow.
  2. The application first will send the user to an authorization request using its client_id and/or client_secret. 
  3. The user will be asked to login to their resource (Infusionsoft) in order to grant permission for the application to use their resource data.  This only needs to be done once as the application can then store the token for subsequent requests.
  4. When the user grants permission for the application to use their resource, a grant code is sent to a url that the application would have specified when sending in the client_id and/or client_secret.
  5. When the application (via the url from above) is sent a grant code, that code is then used to generate an access_token.  The application does this by making a request to the authentication server with the client_id, client_secret, and grant code.  Assuming that those credentials are valid, the authentication server will then return an access_token that will be used to connect directly with the resource server.
  6. When the application has received the access_token, it will store it in its database (encrypted) for later use.  Usually an access_token will only be valid for a certain period of time and therefore sometimes comes with a refresh_token which can be used to get a new access_token.  The refresh_token should be stored along with the access_token.
  7. The application is now free to connect with the resource server and do whatever is intended. Every call made to the resource server will require the access token.

How do I set up an Infusionsoft OAuth API connection

So now that you understand how OAuth 2 works in general, (simple right?) what is the procedure for setting it up for Infusionsoft?

Essentially an Infusionsoft OAuth 2 connection can be set up in any language, but they have provided a wrapper for use with PHP to simplify the process as well as make xml-rpc calls more simple and readable. You can install the PHP SDK from composer or download it directly from github at https://github.com/infusionsoft/infusionsoft-php.  The link also provides more documentation on how to use the SDK.

Essentially there are 3 steps in Authenticating the application.

  1. Send the user to Infusionsoft to Authorize the application. 
    require_once 'vendor/autoload.php';
$infusionsoft = new \Infusionsoft\Infusionsoft(array( 
    'clientId' => 'XXXXXXXXXXXXXXXXXXXXXXXX', 
    'clientSecret' => 'XXXXXXXXXX', 
    'redirectUri' => 'http://myapplicationurl.com/myapplicationauthorizationscript.php'
)); 
echo 'Click here to authorize;';
  2. Accept the grant back from Infusionsoft after the user has logged in an granted permission. 
    require_once 'vendor/autoload.php';

$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId'     => 'XXXXXXXXXXXXXXXXXXXXXXXX',
    'clientSecret' => 'XXXXXXXXXX'
));

/** 
 * This will send the grant code to Infusionsoft and return an access token
 * expiration, and refresh token that you can store in your database.  It will also
 * set the token for you so that you are ready to make calls to the API.
 */
$infusionsoft->requestAccessToken($_GET['code']);

// you should encrypt this array after you serialize it for security.
$token_array = serialize($infusionsoft->getToken());

// store $token_array somewhere and/or begin making API calls
  3. Get the token from the database and set it for making calls to the API 
    require_once 'vendor/autoload.php';

// Decrypt and unserialize the token object from your database
$token_array = some_method_for_retrieving_and_unserializing_token();

// Set up your Infusionsoft object.
$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId'     => 'XXXXXXXXXXXXXXXXXXXXXXXX',
    'clientSecret' => 'XXXXXXXXXX'
));

// Set the token
$infusionsoft->setToken($token_array);

// Now you are ready to make calls to the API

     

And that’s it!  Now you are ready to start building an application that connects to Infusionsoft via the API.

Get Referral Partner Info

groupreflect_photo-1450609283058-0ec52fa7eac4A client recently asked if they could get the name of the contact’s referral partner to a custom field on the contact’s record. That is, if “John Smith” had been attributed as the referral partner responsible for brining in “Jane Parker” as a lead, they wanted “John Smith” to appear in a custom text field called “Referredby”. That field would then be synchronized to a different system being used for reporting and accounting.

Unfortunately the way Infusionsoft is structured, it’s not easy to get from the contact record to the referral partner’s record and vice versa. However, with Pocket Developer’s Any Text, Anywhere plugin and Advanced Merge Notation, we were able to do it with one HTTP Post. Here’s what we did.

First, we are going to go the the Referral table and retrieve the Affiliate Id we find there that is associated with the current contact’s Contact Id by using a “prefetch” (which we number 0, because order matters and we always start with 0):

prefetch[0][affid] = Referral.AffiliateId.FilterBy(ContactId:~Contact.Id~)

Here we are making “affid” the name for “the Affiliate Id you find on the Referral table when you filter it to look for the Contact Id that matches the current contact’s id”. (You could use any word-like string you want as long as you use the same name in the next value.)

Next, we are going to go to the Affilate table and retrieve the Contact Id we find there that is associated with the Affiliate Id we just prefetched. We’ll call it “conid”.

prefetch[1][conid] = Affiliate({affid}).ContactId

We only want to find one record, so right after the table name we add parentheses to contain the specific record we are looking for. We prefetched that affiliate number in the previous step, so we use the name we gave it — “affid” — inside brackets and put it inside the parentheses.

Now we have the contact id of the referral partner saved with the name “conid”. We want to get the first and last name of that contact id, so we want to go to the Contact table and find that specific record. Again, we’re going to use parentheses after the table name, with the specific number we are looking for inside those parentheses, to get the information we want:

prefetch[2][first] = Contact({conid}).FirstName
prefetch[3][last] = Contact({conid}).LastName

We finally have the first and last name, called “first” and “last”. Now we just have to tell AnyText what it should cope and where it should copy it to:

textToSave[0] = {first} {last}
saveTo[0] = Contact._Referredby

In this case, we’re saving the first and last name we prefetched into the Referredby custom field.

If we wanted to get additional information from the affiliate’s record, we would do additional prefetches (incrementing the number and naming each uniquely). And if we wanted to save to additional fields, we would add textToSave–saveTo pairings (incrementing the paired numbers).

And that’s it!

HTTPPost_ReferralPartnerInfo

How to send billing reminders for upcoming subscription payments

The problem: You want to send customers an email that their subscription payment is coming up.
The usual solution: Set up a billing reminder loop sequence
A loop sequence runs repeatedly when triggered from a tag that is removed at the beginning of the sequence and added again at the end. With delays set correctly, a looping sequence will run indefinitely on the prescribed time frame.
1. Set up a campaign that triggers when a tag such as “Trigger Next Billing Cycle” is added.
2. Add five elements to the campaign.
a) Remove tag “Trigger Next Billing Cycle”
b) A delay of the subscription payment interval minus the number of days in advance you want to notify the customer that payment will occur. (For example, if the subscription is paid every 30 days and you want to notify them two days in advance, set the delay for 28 days.)
c) The email to be sent
d) A delay of the number of days in advance you are notifying the client
e) Add tag “Trigger Next Billing Cycle”
3. Make sure the product purchase adds the “Trigger Next Billing Cycle” tag.
Shortcomings of the usual solution:
1. The notification date approximates the billing date, but may not be precise.
2. You can’t put the date of the actual billing in the email.
3. If the date of the subscription billing is changed manually, the contact’s billing cycle campaign must be manually adjusted as well.
4. The process runs indefinitely, so if the subscription is cancelled or limited in number (a payment plan), the notification campaign must be turned off manually or via some other process.
TAG Solution: Store the “Next Billing Date” in a field on the contact record.
When the Next Billing Date is stored in a field on the contact record, you can use a field timer rather than a delay timer to send out the notification email. (Note: The field you use must be a DATE type field. It can be a custom field you create or an existing field such as Anniversary. DATE/TIME fields will NOT work.)
1. Set up a campaign that triggers when a tag such as “Trigger Next Billing Cycle” is added.
2. Add elements to the campaign.
Screenshot 2016-01-18 12.17.47
a) Remove tag “Trigger Next Billing Cycle”
a) An HTTP Post for AnyDate to write the next billing date from the subscription to the Next Billing Date field
HTTPPost_AdvanceBillingNotices
b) A field timer set to run the appropriate number of days before the Next Billing Date
c) The email to be sent
d) A field timer set to run the day after the Next Billing Date
e) Apply tag “Trigger Next Billing Cycle”
3. Make sure the product purchase adds the “Trigger Next Billing Cycle” tag.
This campaign uses the actual billing date on the subscription to trigger the notifications. Because the Next Billing Date is stored in a field on the contact record, you may choose to merge that date into the email. Additional PDev plugins to ActivateSubscription, DeactivateSubscription, and UpdateSubscriptionBillingDate plugins to handle changes in subscriptions and stop, restart, or change the billing notices along with the subscription dates via notes applied or other triggers.

NOTE: If customers may have more than one subscription, multiple campaigns and Advanced Merge Notation will be needed to ensure selection of the correct Next Bill Date from the correct subscription.

©2023 The API Guys