• Introduction
• Key terms and concepts
• What is XML-RPC?
• What is REST?
• Key differences between XML-RPC and REST
• OAuth 2.0 Authentication for REST v2
• Migration Overview
• Migrations steps
• Best practices
• SDKs
• Resources
• How to get support

Introduction

Purpose of this document

The purpose of this document is to guide technical teams and integration partners through the process of migrating from Keap’s XML-RPC API to our new v2 REST API. This transition is essential to ensure continued compatibility with the latest versions of the Keap platform and to take advantage of improvements in security, performance, scalability, and maintainability offered by the REST architecture.

Background

The XML-RPC protocol is a legacy integration technology that predates many of today’s web standards. While it has been widely used over the years, it presents several limitations in areas such as standardization, error handling, and authentication.

 
To overcome these challenges, the v2 REST API was developed using modern web standards like HTTP/JSON, OAuth 2.0, and a resource-based structure that provides a more intuitive and scalable approach to building integrations.

Specific objectives

• Explain the key differences between XML-RPC and REST v2.
• Explain how to authenticate and manage OAuth 2.0 tokens in REST v2.
• Outline the steps required to migrate existing integrations.
• Provide practical examples showing method-to-endpoint equivalences.
• Minimize technical impact and migration risks.

Intended audience

This guide is intended for:

• Developers and technical teams currently maintaining XML-RPC integrations.
• Partners and consultants building or supporting Keap-based solutions.
• Product owners and administrators who need to plan and oversee the migration process.

Key terms and concepts

• API (Application Programming Interface): A set of rules that allow software systems to communicate with each other.
• Endpoint: A specific URL that represents an API resource or operation (e.g., /v2/contacts).
• Protocol: The set of communication rules and formats used by the API; XML-RPC uses XML over HTTP, while REST v2 uses JSON over HTTP.
• Resource: An object or entity exposed by the API, such as contact, company, or note.
• HTTP Methods: Standard verbs used to interact with resources: GET (read), POST (create), PATCH (update), DELETE (remove).
• Payload: The data sent to or received from the API, usually formatted as JSON in REST v2.
• OAuth 2.0: A secure authorization protocol that lets applications access data without exposing user credentials.
• Access Token: A short-lived credential used to authenticate API requests.
• Refresh Token: A long-lived credential used to obtain new access tokens when they expire.
• Rate Limiting: A restriction on how many API requests can be made within a given time.
• OpenAPI Specification: A standard format (formerly known as Swagger) used to describe REST APIs and generate SDKs automatically.
• SDK (Software Development Kit): A set of prebuilt tools, libraries, and examples that simplify interaction with the Keap REST v2 API.

What is XML-RPC?

XML-RPC is a remote procedure call protocol that uses XML to encode its calls and HTTP as a transport mechanism. It allows clients to execute functions on a remote server, but its structure is rigid and lacks support for modern standards like JSON or OAuth 2.0.

What is REST?

REST (Representational State Transfer) is an architectural style that uses standard HTTP methods and typically exchanges data in JSON format. It’s widely adopted for its simplicity, scalability, and alignment with modern web technologies.

Key differences between XML-RPC and REST

As shown above, the transition from XML-RPC to REST v2 represents a shift toward a more modern, secure, and efficient integration model. Each improvement whether in authentication, performance, or data handling—has been designed to simplify development, enhance reliability, and ensure long-term compatibility with the evolving Keap platform.

OAuth 2.0 Authentication for REST v2

REST v2 uses OAuth 2.0 to authorize API requests securely. In this flow, your application obtains an access token that must be included in the Authorization header of each request. Access tokens have a limited lifetime, so your integration may need to refresh tokens periodically to maintain access. OAuth 2.0 ensures that API credentials are never exposed directly in requests, and it allows fine-grained control over permissions. For detailed guidance on obtaining and managing OAuth tokens, see Getting Started with OAuth Keys

Migration Overview

Migrating from XML-RPC to REST v2 involves analyzing your existing API usage, identifying equivalent REST endpoints, updating authentication mechanisms, and validating results. The following sections describe each phase in detail.

Migrations steps

Step 1:  Assess existing integrations

Before making any changes, identify all XML-RPC methods currently used in your integration and document which parts of your system depend on each method. Include sample requests and responses if available, as these will help when converting data to JSON for REST v2. To locate all XML-RPC calls in your codebase, you can use the Python script provided below, which scans your project recursively, ignores common dependency and build folders, and exports all matches to a CSV file for easy analysis:

Python 
 
import os 
import re 
import csv 
from concurrent.futures import ThreadPoolExecutor 
from pathlib import Path 
ROOT_DIR = '.' 
PATTERNS = [ 
	r'data\(',                      
    r'DataService',                   
    r'xmlrpc',                        
    r'xml',                            
] 
 
# Add more extensions if you're using other languages 
# e.g., '.cpp', '.c', '.cs', '.swift', '.kt', etc. 
EXTENSIONS = {'.py', '.php', '.js', '.java', '.rb', '.go', '.ts', '.jsx', '.tsx'} 
 
IGNORE_DIRS = { 
	'node_modules', 'vendor', '__pycache__', '.git', 
	'dist', 'build', 'target', 'out', 'bin', '.venv', 'venv' 
} 
OUTPUT_CSV = 'xmlrpc_calls.csv' 
MAX_FILE_SIZE = 5 * 1024 * 1024  # 5MB 
def should_process_file(file_path): 
	"""Quick filter before processing file""" 
	path = Path(file_path) 
     
	if path.suffix.lower() not in EXTENSIONS: 
    	return False 
	try: 
    	if path.stat().st_size > MAX_FILE_SIZE: 
        	return False 
	except: 
    	return False 
	return True 
 
def search_file(file_path): 
	"""Search for patterns in file""" 
	if not should_process_file(file_path): 
    	return [] 
     
	results = [] 
	try: 
    	with open(file_path, 'r', encoding='utf-8', errors='ignore') as f: 
        	for i, line in enumerate(f, 1): 
            	for pattern in PATTERNS: 
                	if re.search(pattern, line, re.IGNORECASE): 
                        results.append({ 
                        	'File': file_path, 
                        	'Line': i, 
                        	'Pattern': pattern, 
                        	'Content': line.strip() 
                    	}) 
	except Exception: 
    	pass 
	return results 
 
def main(): 
    files_to_search = [] 
	for root, dirs, files in os.walk(ROOT_DIR): 
        dirs[:] = [d for d in dirs if d not in IGNORE_DIRS] 
    	for file in files: 
            file_path = os.path.join(root, file) 
        	if should_process_file(file_path): 
                files_to_search.append(file_path) 
	results = [] 
	with ThreadPoolExecutor(max_workers=os.cpu_count()) as executor: 
    	for file_results in executor.map(search_file, files_to_search): 
            results.extend(file_results) 
 
	with open(OUTPUT_CSV, 'w', newline='', encoding='utf-8') as csvfile: 
    	fieldnames = ['File', 'Line', 'Pattern', 'Content'] 
    	writer = csv.DictWriter(csvfile, fieldnames=fieldnames) 
        writer.writeheader() 
    	for r in results: 
            writer.writerow(r) 
 
    print(f'Scan complete. Results saved to {OUTPUT_CSV}') 
 
if __name__ == '__main__': 
    main()

Step 2: Identify equivalent REST v2 endpoints

Once you have a clear inventory of the XML-RPC methods your integration uses, the next step is to identify the corresponding REST v2 endpoints. Each XML-RPC method generally maps to a resource-based REST endpoint, although the structure and payload format may differ.

To simplify this process, we have prepared a mapping document that lists each commonly used XML-RPC method alongside its equivalent REST v2 endpoint. You can find the document here.

Note: A small number of XML-RPC methods will not be converted to REST v2.  See this article and the GapAnalysisJustifications.xlsx spreadsheet for details and recommended alternatives.

When mapping your calls, pay attention to required fields and data formats, as these may differ between XML-RPC and REST v2. For the full documentation on parameters, expected payloads, and responses for each REST v2 endpoint, refer to: Keap REST v2 API Documentation.

Step 3:  Refactor API calls

After mapping XML-RPC methods to their REST equivalents and setting up OAuth 2.0 authentication, the next step is to refactor the API calls by replacing XML-RPC requests with REST requests. Unlike XML-RPC, REST endpoints are resource-based, meaning calls operate on resources using standard HTTP verbs (GET, POST, PATCH, DELETE) rather than invoking methods. This requires converting the previous XML payloads into JSON format and adapting the request and response handling to modern data structures. For example, an XML-RPC call to ContactService.add is replaced with a POST request to /v2/contacts, sending the contact data as a JSON object and receiving a JSON response.

When implementing REST calls, you can also consider using our available SDKs, which support multiple programming languages and are documented in the Resources section of this document. If SDKs are not used, any modern HTTP client can be utilized, but it is important to manage headers, error responses, and pagination explicitly. Errors in REST v2 are returned as structured JSON messages with HTTP status codes. Integrations should handle errors properly by interpreting these codes and logging detailed information for debugging and monitoring purposes. Common HTTP status codes are summarized in the table below:

The following example demonstrates a minimal API call to create a new contact using REST v2. It includes only the required fields (given_name, family_name, and at least one email_addresses entry) to illustrate the basic structure of a request and how to send JSON data to the /contacts endpoint. This serves as a starting point for implementing more complete integrations.

PHP  
 
 'https://api.infusionsoft.com/crm/rest/v2/', 
	'headers' => [ 
    	'Authorization' => 'Bearer YOUR_ACCESS_TOKEN', 
    	'Content-Type' => 'application/json' 
	] 
]); 
$payload = [ 
	'given_name' => 'John', 
	'family_name' => 'Doe', 
	'email_addresses' => [ 
    	['email' => 'john.doe@example.com', 'field_type' => 'EMAIL1'] 
	] 
]; 
$response = $client->post('contacts', ['json' => $payload]); 
$data = json_decode($response->getBody(), true); 
 
echo "Contact created successfully. ID: " . $data['id'] . PHP_EOL;

Note: This is a minimal example to illustrate how to make a REST v2 API call. In production, you should implement proper error handling, logging, and retries as needed.

Step 4: Test and validate

After refactoring your API calls to REST v2, it is essential to thoroughly test and validate your integration to ensure that data is correctly mapped and functionality is preserved. Start by comparing responses from the old XML-RPC calls with the new REST responses to confirm that all required information is returned and correctly structured.

Validate that mandatory fields are populated and that data formats, such as dates or numbers, comply with the REST API requirements. It is also important to test common error scenarios, including invalid input, unauthorized requests, forbidden access, missing resources, rate-limiting, and server errors, to ensure that failures are handled properly.

Logging and monitoring during testing are critical to quickly identify discrepancies or unexpected behavior. Whenever possible, implement automated tests to validate both individual components and end-to-end API interactions. This approach helps ensure that your integration is reliable, maintainable, and ready for production deployment.

By completing the refactoring and thoroughly testing your integration, you can be confident that your system now works with REST v2 and that all critical data and functionality have been preserved. While the migration process is complete at this point, following best practices will help ensure your integration remains reliable, maintainable, and scalable over time. The next section provides practical guidance to optimize your REST v2 integration for long-term success.

Best practices

• Centralize authentication handling: Manage OAuth tokens in a single location to simplify refreshing, storage, and reuse.
• Handle errors gracefully: Check HTTP status codes, log relevant information, and consider retries for transient errors such as rate-limiting or server errors.
• Validate inputs and outputs: Ensure data sent to the API meets required formats and constraints and verify responses to detect missing or malformed data early.
• Implement consistent logging and monitoring: Capture request and response details and monitor API usage and performance to quickly identify issues.
• Design for scalability: Structure your code to handle multiple resources, large datasets, and potential rate limits. Avoid hardcoding values or limiting your integration to a single scenario.
• Document your integration: Maintain clear internal documentation describing endpoints used, business rules, and integration logic to simplify future maintenance and onboarding.
• Participate in scheduled brownouts: Join our brownouts during 2026 to test your integration under controlled conditions and verify its behavior during temporary service interruptions. 
• Do not abuse the API: Although throttling is handled automatically, excessive requests may impact your integration’s performance or trigger temporary limits.

SDKs

Keap provides official SDKs for multiple programming languages to simplify integration with the REST v2 API. These SDKs are automatically generated from Keap’s OpenAPI Specification and maintained in the Keap SDK GitHub repository. 

Resources

• REST v2 api documentation
• Getting started with OAuth2
• XML-RPC endpoints not supported in REST v2
• XML-RPC to REST v2 mapping
• SDKs

How to get support

For questions or guidance during migration, you can contact our API Specialist, Omar Almonte, in the Keap Developer Forum.