The API Guys

We Integrate Systems

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.

Update Opportunity Records with a Web Form

flashlight_photo-1460804198264-011ca89eaa43We love opportunity records, because a single contact can have more than one, and because you get another 100 custom fields for each one. We like use them for a lot of things that are not the typical manually-handled sales pipeline that Infusionsoft teaches, and we’ve developed some interesting techniques for working with them.

One of our Pocket Developer customers recently asked about how to have assistants use an Infusionsoft web form to update opportunity records. For an added wrinkle, a given contact might have multiple opportunity records active at the same time.

There are two problems with this scenario. First, Infusionsoft web forms can only input data to contact records, not opportunities. Second, since there are multiple opportunities, we need to be able to designate the specific opportunity to add data to. Fortunately both of these problems can be handled with Pocket Developer, with a little finessing. It requires a teeny, tiny bit of html code and an understanding of URL query strings… which I am going to explain thoroughly below, so you’ll be up and running in no time at all.

1) Create a campaign with whatever goal trigger you want to start with.

2) Add a sequence and add two processes to the sequence:
a) Create an Opportunity — set the default options (title, stage, assigned user, etc.) to whatever you wish them to be.
b) An HTTP Post to Email Anyone. Set the “to” parameter to the email of the person you will want to fill out the form (or a field containing that information), and the templateId to the id number of the email template that will be sent to them.

3) Add a web form goal. This web form must have a field for email and a field to temporarily store the opportunity id. The opportunity id storage field can be a custom field, but since it is for temporary storage you may also choose to use a standard field that you don’t typically use. We often use the Assistant Name field for this purpose. The email and opportunity id fields can be hidden if you like, since we are going to automatically populate them with the link. You should of course also have temporary storage fields for any other information you want the user to add.

4) Copy the hosted link for the web form.

5) Go to the email template you entered in step 2a. Insert an html snippet in the body of the email. (This is where the teeny, tiny bit of code comes in.) Paste in the following:

<a href="url">Link Text</a>

This is how a link is created. <a href=”url”> says to add a link that goes to a url (we’ll add the actual url in the next step). The </a> says to stop linking. The “Link Text” in between is the text that will be made clickable by the other two parts. That’s it… all the code you need to know. (If you want to know more about html links, click here.)

6) Replace what is between the quotation marks with the hosted web form link you copied in step 4.

7) In addition to the url, we need to send a couple of pieces of data to pre-fill the form — the email address and the opportunity id. (This is where you find out about query strings. For a more thorough explanation, click here.) In order to separate this information from the url, we’re going to add question mark. Then we’re going to send in pairs of information in the format “name=value” with each pair separated by an ampersand. For example, if we needed to tell it to set the email address to “hello@theapiguys.com” and the assistant name (which we are using to store the opportunity id) to “1234”, we would add the following to the url:

?Email=hello@theapiguys.com&AssistantName=1234

Because of the way the hosted web form is coded, it will know to put the Email value into the Email field and the AssistantName value in the AssistantName field. (Note that this technique will also work if you use the Infusionsoft javascript snippet to embed your web form on your website, though in that case you will have a different url.)

But we don’t always want to send the same information. We want these values to be dynamic and send the email for the relevant contact and the opportunity id of the opportunity we just created. In order to do this, we will use merge fields. Fortunately since we’re using Email Anyone, we can even directly merge in data from opportunity records, like so:

?Email=~Contact.Email~&AssistantName=~Opportunity.Id~

When the email is generated, Infusionsoft will see this html snippet and perform the merges like it does in any other place in the email. It will transform ~Contact.Email~ into the contact’s id number and it will transform ~Opportunity.Id~ into the id number of the most recently updated (which in this case has to be the one we just created).

Note that this method does have a few drawbacks. Because you are using an html snippet for the link, it will not behave like a regular Infusionsoft link. It won’t be tracked, and there’s no way to add actions like a tag based on the link click. It also cannot complete a link click goal. So this is probably NOT a method you want to use for marketing-type emails. But for administrative purposes, this method can be very useful.

Now you’ve got your web form ready and your email template set up. When the administrator gets the email, they will click on the link and be directed to the webform, which will pre-populate with the values you’ve sent in the query string for those field, including the opportunity id. But they’re still inputting data to the contact record. It’s time to make the real magic happen… getting that info to the opportunity record.

8) Add a sequence with an HTTP Post to AnyText to copy the stored data from the contact record to the opportunity record.

Set the textToSave fields to the fields from your contact record where the data you want to copy to the opportunity is stored.

In the saveTo fields you will use reference notation to merge in the opportunity id storage field, thereby designating precisely which opportunity to write to. Reference notation looks like this:

Table(ID).FieldName

or more specifically in this case

Opportunity(~Contact.AssistantName~)._OtherInfo

The Contact.AssistantName field is where the opportunity id is stored, having been sent in by the web form which was pre-filled by the html link you created. The reference notation will go to the opportunity table, look for the entry in that table that matches what it finds in the Contact.AssistantName field, and (since this is a saveTo value) will write the matching textToSave information to the OtherInfo field for that entry.

9) (Optional) If you like to keep your data clean, you can add a short timer (a couple minutes to make sure the http post has completed copying the data) and then add another HTTP Post to AnyText to set the copied contact fields back to blank. That way, you don’t get confused by potentially old date sitting in those fields. We’ve even used this technique to prevent users from accidentally filling out the form too quickly in succession by adding a warning if the AssitstatName field is still occupied. This is especially useful when users might be handling multiple opportunities at once.

Now your system is set up so that you can update opportunity records from a web form.

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

FieldMath for Sequential Numbering

Infusionsoft keeps ID numbers for everything — contacts, orders, opportunities, etc. — but they aren’t always what you want. For one thing they frequently go by twos, and for another they count all items of that type. So what if you want your own sequential numbering system? Use Field Math.

FieldMath_JobNumber_increment

1. Create a custom field on the record type you want to sequentially number.
2. Add a Field Math HTTP Post in a campaign sequence at the point you want the number to increment, such as immediately after a purchase or entry into a particular opportunity stage.
3. For the variable, use the custom field name plus .Global.Max to get the max value currently stored in that field on any record.
4. For the formula, use a+1.
5. For the saveTo field, use the custom field name (no tildes!).

When the contact reaches that part of the campaign, Field Math will find the highest value of the number in that field on any record, add one, and save the number into the field on the current record. The record will be numbered sequentially.

©2023 The API Guys