Getting started overview

Integrating with the FullContact API involves a sequence of steps designed to provide access to its data enrichment capabilities. This guide focuses on the initial setup, from creating an account and obtaining credentials to executing a first API call. The FullContact API is primarily used for enhancing profiles of individuals and companies with additional data points, supporting applications in areas such as personalization, marketing segmentation, and fraud detection. The API offers RESTful endpoints, with comprehensive FullContact API reference documentation available to developers.

The process generally follows these stages:

  1. Account Creation: Registering on the FullContact platform.
  2. API Key Generation: Obtaining the necessary authentication credential.
  3. First API Request: Constructing and sending a basic query to a FullContact endpoint.
  4. Response Handling: Interpreting the data returned by the API.

FullContact provides a FullContact pricing page that details a free tier allowing up to 500 API calls per month, suitable for initial development and testing. Paid plans, such as the Growth tier, commence at $99 per month for 5,000 calls.

Create an account and get keys

To begin using the FullContact API, an account must be created on the FullContact website. This process typically involves providing basic contact information and agreeing to the terms of service.

Account Creation Steps:

  1. Navigate to the FullContact pricing page.
  2. Select the 'Start Free' or a relevant paid plan option to begin the registration process.
  3. Complete the registration form, providing required details such as email address and password.
  4. Verify your email address if prompted, which is a common step for new account activations.

Retrieving Your API Key:

After successful account creation and login, your API key will be accessible within the FullContact dashboard. The API key serves as the primary method for authenticating your requests to the FullContact API.

  1. Log in to your newly created FullContact account.
  2. Locate the 'API Keys' or 'Developer' section within your account dashboard.
  3. Your unique API key will be displayed there. It is crucial to treat this key as sensitive information, similar to a password, to prevent unauthorized access to your account and API usage.
  4. Copy the API key for use in your application. For security best practices regarding API keys, refer to general guidelines on securing API keys in cloud environments.

Your first request

Once you have your API key, you can make your first request to test the integration. The FullContact Person Enrichment API is a common starting point, allowing you to query data based on an email address.

API Endpoint and Authentication

The base URL for the FullContact API is https://api.fullcontact.com/v3/. All requests must include your API key in the Authorization header using the Bearer token scheme. For example: Authorization: Bearer YOUR_API_KEY.

Example: Person Enrichment API

This example demonstrates how to make a request to the Person Enrichment API using an email address.

Request Details:

  • Endpoint: /person.enrich
  • Method: POST
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer YOUR_API_KEY
  • Body: { "email": "[email protected]" }

cURL Example:

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

Expected Response (Partial Example):

A successful response will return a JSON object containing enriched data for the provided email, if found. The structure will vary based on the available data.

{
  "message": "OK",
  "status": 200,
  "requestId": "aBcDeFg12345",
  "traits": {
    "gender": "Female",
    "ageRange": "25-34",
    "fullName": "Jane Doe"
  },
  "demographics": {
    "locationDeduced": {
      "city": {
        "name": "Boulder"
      },
      "state": {
        "name": "Colorado",
        "code": "CO"
      },
      "country": {
        "name": "United States",
        "code": "US"
      }
    }
  },
  "organizations": [
    {
      "name": "Example Corp",
      "title": "Software Engineer"
    }
  ],
  "socialProfiles": [
    {
      "type": "twitter",
      "username": "janedoe",
      "url": "https://twitter.com/janedoe"
    }
  ]
}

Quick Reference for Getting Started

This table summarizes the initial steps:

Step What to Do Where
1. Sign Up Create a FullContact account. FullContact Pricing Page
2. Get API Key Locate and copy your API key from the dashboard. FullContact Account Dashboard (API Keys section)
3. Make Request Send a POST request to /v3/person.enrich with an email. Your preferred HTTP client (e.g., cURL, Postman, Python requests)
4. Verify Response Check for a status: 200 and returned data. HTTP client output

Common next steps

After successfully making your first API call, you can explore more advanced features and integrate the FullContact API into your applications.

  1. Explore Other Endpoints: Investigate the Company Enrichment API for business data, or the Identity Resolution API for linking disparate identifiers.
  2. Implement Error Handling: Develop robust error handling mechanisms to manage various API responses, including rate limits (status 429), bad requests (status 400), and authentication failures (status 401). The FullContact error codes documentation provides a comprehensive list.
  3. Integrate into Applications: Embed the API calls into your existing software, CRM, or marketing automation platforms. Consider using server-side integration to protect your API key.
  4. Monitor Usage: Regularly check your API usage within the FullContact dashboard to stay within your plan's limits and monitor costs.
  5. Review SDKs (if available): Although no official SDKs are listed, community-contributed libraries might exist for popular programming languages, which can simplify API interaction.
  6. Optimize Queries: For large-scale operations, learn about batch processing options or query optimization strategies to maximize efficiency and minimize API calls.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Check API Key: Ensure your API key is correctly included in the Authorization: Bearer YOUR_API_KEY header. A missing or incorrect key will result in a 401 Unauthorized error. Double-check for typos or leading/trailing spaces.
  • Verify Endpoint and Method: Confirm that you are sending the request to the correct URL (e.g., https://api.fullcontact.com/v3/person.enrich) and using the specified HTTP method (e.g., POST). Refer to the FullContact documentation for specific endpoint details.
  • Content-Type Header: For POST requests with a JSON body, ensure the Content-Type: application/json header is set. Incorrect content types can lead to 400 Bad Request errors.
  • Request Body Format: Validate that your JSON request body is correctly formatted. Even a small syntax error can cause the API to reject the request. Tools like online JSON validators can assist.
  • Rate Limiting: If you receive a 429 Too Many Requests error, you have exceeded your plan's API call limits. Wait before retrying or consider upgrading your plan. The free tier has a limit of 500 calls per month.
  • Network Connectivity: Ensure your development environment has stable internet access and is not blocked by firewalls or proxy settings from reaching the FullContact API domain.
  • API Status Page: Check the FullContact status page (if available) for any ongoing service outages or maintenance that might affect API availability.
  • Consult Documentation: The FullContact API error codes section in the official documentation provides detailed explanations for specific error messages, which can help pinpoint the exact problem.