FullContact Getting Started: Account, Keys, and First API Call 2026

Getting started overview

To begin integrating with FullContact, developers typically follow a sequence of steps that involve account creation, API key retrieval, and executing a foundational API request. FullContact provides a developer-focused ecosystem that includes a free tier, documentation, and client libraries to facilitate this process. The core objective of the initial setup is to establish authenticated access and validate the API connection with a simple data enrichment call.

The process outlined here focuses on the essential steps for a quick start:

1. Sign up for a FullContact developer account.
2. Locate and secure your API key.
3. Make an authenticated request to a FullContact API endpoint.

This guide uses the Person API as an example, which is one of FullContact's primary offerings for enriching contact data related to individuals. For more detailed information on other APIs like the Company API or Address API, consult the FullContact API Reference.

Create an account and get keys

Access to the FullContact API requires an active account and valid API credentials. FullContact offers a Developer plan that includes 100 free API calls per month, suitable for initial testing and development.

Account creation

Follow these steps to create your FullContact account:

1. Navigate to the FullContact pricing page.
2. Select the "Developer" plan and proceed with the registration.
3. Complete the required fields for account setup, including email verification.

Once registered, you will gain access to the FullContact developer portal, which serves as the central hub for managing your account, API keys, and monitoring usage.

API key generation and retrieval

API keys are essential for authenticating your requests to FullContact's services. These keys link your API calls to your account and track usage against your plan limits.

1. Log in to your FullContact developer portal.
2. Locate the "API Keys" section, typically found in the dashboard or settings menu.
3. Generate a new API key if one is not already provided.
4. Copy and securely store your API key. Treat this key as sensitive information, similar to a password, to prevent unauthorized access to your account and API usage.

Your first request

After obtaining your API key, the next step is to make a successful API call. This section demonstrates how to use the FullContact Person API to enrich data for an email address using a cURL command. This example is designed to be executable in most command-line environments without requiring a specific SDK.

Making an API call with cURL

The FullContact Person API allows you to retrieve public profile information associated with an email address. The endpoint typically expects a POST request with a JSON body containing the email and an API key in the headers or as a query parameter (though headers are generally preferred for security).

Example Request (Person API by Email):

curl -X POST \ 
  'https://api.fullcontact.com/v3/person.enrich' \ 
  -H 'Content-Type: application/json' \ 
  -H 'X-FullContact-ApiKey: YOUR_API_KEY' \ 
  -d '{ "email": "[email protected]" }'

Replace YOUR_API_KEY with the actual API key you retrieved from your FullContact developer portal. The email address [email protected] is often used in FullContact's documentation for example requests.

Understanding the response

A successful request will return a JSON object containing enriched data for the provided email address. This data may include social profiles, demographic information, and professional details, depending on the availability of public data. An example of a successful response structure might include:

{
  "status": 200,
  "requestId": "a1b2c3d4e5f6g7h8i9j0",
  "person": {
    "fullName": "Brian X. Doe",
    "gender": "male",
    "ageRange": "35-44",
    "demographics": {
      "location": "Denver, CO"
    },
    "socialProfiles": [
      {
        "type": "twitter",
        "url": "https://twitter.com/brianxdoe",
        "username": "brianxdoe"
      }
    ],
    "organizations": [
      {
        "name": "FullContact",
        "title": "CEO"
      }
    ]
  }
}

If an error occurs, the response will typically include an HTTP status code indicating the error (e.g., 401 Unauthorized for an invalid API key, 404 Not Found if no data is found for the input, or 400 Bad Request for malformed input) and an error message in the JSON body. For a comprehensive list of status codes and error messages, refer to the FullContact API Error Codes documentation.

Using SDKs

FullContact provides client libraries (SDKs) for several popular programming languages, which can simplify API interaction by handling authentication, request formatting, and response parsing. Supported SDKs include Python, Node.js, Ruby, PHP, Java, and .NET. While cURL is useful for initial testing, integrating an SDK is generally recommended for production applications.

Common next steps

After successfully making your first API call, you can explore more advanced features and integrations. Here are common next steps:

Explore other APIs

FullContact offers several APIs beyond the Person API, including:

• Company API: Enriches data about organizations based on domain names.
• Address API: Provides information about physical addresses.
• Identity Resolution: Connects disparate data points to form a unified customer view.

Each API has specific endpoints and data enrichment capabilities. Review the FullContact API reference for detailed endpoint documentation and request parameters.

Integrate with SDKs

For ongoing development, integrating one of FullContact's official SDKs can streamline your workflow:

• Python SDK: Simplifies interaction for Python applications.
• Node.js SDK: Ideal for JavaScript-based backend services.

SDKs often manage common API tasks such as retry logic, rate limiting, and request signing, reducing development overhead. For example, the Python SDK simplifies making a Person API call as illustrated in the Python Person API example.

Monitor usage and upgrade plans

The FullContact developer portal provides tools to monitor your API usage, track call volumes, and manage your subscription. If your application requires more than the 100 calls per month offered by the free Developer plan, you can upgrade to a paid plan, with the Growth plan starting at $99/month for 10,000 calls.

Implement webhook notifications

For asynchronous data updates or processing, FullContact supports webhooks. Webhooks allow FullContact to notify your application when data enrichment is complete or when certain events occur, eliminating the need for polling. This is a common pattern for event-driven architectures, as described in guides like AWS EventBridge documentation on event-driven architectures. Consult the FullContact documentation for setting up webhooks.

Troubleshooting the first call

Encountering issues during your first API call is not uncommon. Here are some troubleshooting tips:

Common errors and resolutions

• 401 Unauthorized: This typically indicates an invalid or missing API key. Double-check that your X-FullContact-ApiKey header value exactly matches the API key from your developer portal. Ensure there are no leading or trailing spaces.

  # Verify API key in curl command
  curl -X POST ... -H 'X-FullContact-ApiKey: YOUR_CORRECT_API_KEY' ...

• 400 Bad Request: This usually means the request body is malformed or missing required parameters. Ensure your JSON payload is valid and includes the necessary fields, such as email for the Person API.

  # Verify JSON payload structure
  curl -X POST ... -H 'Content-Type: application/json' -d '{ "email": "[email protected]" }'

• 403 Forbidden: Your account might not have the necessary permissions for the requested endpoint, or you may have exceeded your rate limits. Check your plan details and API usage in the developer portal.
• 429 Too Many Requests: You have exceeded the API rate limits for your current plan. Implement exponential backoff for retries to handle this gracefully, as recommended by Stripe's API rate limit guidance.
• No data returned (but 200 OK): If you receive a 200 OK status but the person object is empty or sparse, it means FullContact could not find public data for the input provided. Try with a well-known email address (like [email protected]) to confirm the API is working.

Quick reference for getting started