FullContact Developer API Documentation
Overview
The FullContact Developer APIs are used to manage and enhance contact information. Use our APIs to provide social profiles in your app, improve contacts in address books, enrich CRM information, or create highly personalized marketing campaigns.
Our APIs are RESTful and can be queried with either HTTP GET or HTTP POST requests. Responses are delivered in JSON or XML format. Some endpoints support HTML or vCard formatted responses. Sign up for a free account to get an API Key and get started.
Response Codes
All successful responses are returned in JSON, XML, HTML or vCard, depending on the response format you request. On our paid endpoints, such as the Person endpoint, you will only be billed for queries that respond with a 200 response code, which indicates that the transaction was completed successfully.
| Status Code | Description |
|---|---|
| 200 OK | Your request processed successfully. |
| 202 Accepted | Your request is currently being processed. You can check again later to see the request has been processed. |
| 400 Bad Request | Your request was malformed. |
| 403 Forbidden | Your API key is invalid, missing, or has exceeded its quota. |
| 404 Not Found | This person was searched in the past 24 hours and nothing was found. |
| 410 Gone | This resource cannot be found. You will receive this status code if you attempt to query our deprecated V1 endpoints. |
| 422 Invalid | Invalid or missing API query parameter. |
| 500 Internal Server Error | There was an unexpected error on our server. If you see this please contact support@fullcontact.com. |
Rate Limiting
Some API endpoints are subject to rate limits that exist independently of your API key's monthly quota. Rate limits are universal: they apply to all types of API response codes. We track rate-limited endpoints on a 60-second basis. For example, if your API is subject to a 10/second rate limit, we'll allow you 600 requests per 60 second window. To make it easier for your application to determine if it is being rate-limited, or if it is likely to be in the future, we've added the following HTTP headers to successful responses:
| Header Name | Example Value | Description |
|---|---|---|
| X-Rate-Limit-Limit | 600 | The rate limit ceiling for your request |
| X-Rate-Limit-Remaining | 10 | The number of requests left in the 60 second window. |
| X-Rate-Limit-Reset | 20 | The number of UTC epoch seconds remaining until the 60 second window resets |
| Thanks to Twitter and Github for this pattern. | ||
Social Network Types
Below is a list of type ids for photos, socialProfiles, and icons returned by the person method.