Requests Overview

When making requests to the Infusionsoft API, you'll be sending defined XML to API services that reside at a URL provided by Infusionsoft.

An "API service" is an exposed endpoint in our system that you can access to perform an operation or to request data. Each service can have multiple operations that can be called. To make a call, you will need to know five things:

  1. The API service URL, provided to you by Infusionsoft Support
  2. All urls to access the API are https://appname.infusionsoft.com/api/xmlrpc Replace appname with your correct subdomain.
  3. The name of the service and the method, as defined by the Service Documentation
  4. The encrypted API key, which you can read more about here {HYPERLINK}
  5. All required parameters to pass to the service, as defined later in this documentation
  6. How the API service will respond to you, as defined later in this documentation

To summarize, you will invoke some command on our servers and pass all the information necessary to complete that command. We will then formulate a response and send it back to you.

Request Authentication

All requests to the Infusionsoft API must be made over a secure HTTP connection (HTTPS). However, authentication is handled by passing your private API Key as a parameter in your XML request, as outlined below.

Request Format

Traditionally, requests to the Infusionsoft API have been documented as requiring XML-RPC. In reality, it is perfectly allowable to send valid XML as a string over HTTP to the endpoint provided to you. XML-RPC as a protocol is powerful, and may programming languages have classes and/or libraries available that make it easy to send XML-RPC requests.

No matter how you send your request, your XML must be valid, properly formatted, and contain the service and method, API Key, and any required parameters to make a valid request.

Though the XML can take any data type that's a string, the endpoint will require certain data types to not balk. The PHP iSDK will handle this for you, but in case you're not using that we've made several considerations. To help you, we've included two data types with each variable. The first data type is what you'll want to output as, and the second is what the endpoint is expecting. Some common ones you'll see are:

  • String int - You'll output the integer as a string. If it's not an integer, the API will return faults.
  • Bool int - The endpoint is expecting a Boolean value, but it should be represented as an integer in the XML.

The XML documents we've outlined for you will help show you how to structure your XML requests, and how to read the responses. However, you still might have questions about what each call does, and what data to send. If you have questions about what a particular function does, or where it would be used, we recommend you consult the documentation for the PHP SDK which specifies what each function does, available here: http://help.infusionsoft.com/developers/services-methods

The first argument in all your XML calls is the service.methodName, and you can match the methodName on the left hand side for more information about the particular arguments something is looking for.

<?xml version="1.0"?>
<methodCall>
  <methodName>service.methodName</methodName>
  <params>
    <param>
      <value><string>privateKey</string></value>
    </param>
    <param>
      <value><int>12345</int></value>
    </param>
  </params>
</methodCall>
					

Handling Arrays and Associative Arrays

One of the main deviations from implementing raw XML versus the PHP SDK is that you'll have to output your arrays, and associative arrays as a collection of arguments in the XML-RPC standard. You can learn more about the Standard here: http://en.wikipedia.org/wiki/XML-RPC

Let's take a look at ContactService.update for an example of how you'll deal with associative arrays in XML.

This method is intended to update one, or all of the fields of a contact. In PHP, you'd simply use an array with the fields for keys. In XML, we need to be a little bit more thorough.

<value><struct>
  <member>
    <name>fieldToUpdate1</name>
    <value><string>field1</string></value>
  </member>
  <member>
    <name>fieldToUpdate2</name>
    <value><string>field2</string></value>
  </member>
</struct></value>
					

In XML, we have a <struct> element and within <members> we put the Member/Value pair. So, to update only the FirstName and Email fields, we would put together a Member/Value request like this:

<value><struct>
  <member>
    <name>FirstName</name>
    <value><string>Jon</string></value>
  </member>
  <member>
    <name>Email</name>
    <value><string>Jon@Doe.com</string></value>
  </member>
</struct></value>
					

It's important to note that anything after the first set of arguments is optional, but you must have at least one member of your struct.

When you're dealing with sending multiple arguments to the same part of the API, you can implement it a little easier. Let's take a look at ContactService.findByEmail as an example for sending multiple pieces of data.

ContactService.findByEmail is designed to let you search the database by Email, and return any of the fields you'd like from the Contacts table. In PHP, you'd just send an array of the fields you'd like returned. In XML, we simply just list the values inside the <array> element surrounded by <value> and <string> tags.

<value><array>
  <data>
    <value><string>Id</string></value>
    <value><string>FirstName</string></value>
    <value><string>LastName</string></value>
  </data>
</array></value>
					

Date Query Format

When requesting data from a specific date or date range, the format for all dates should follow: YYYY-MM-DD. You may also use the wildcard operator, %, to query data from many dates. For example, to get results from every day for a specific month, you would use 2012-03-%.