Introduction | Selling.com API Documentation

Enrichment API

Welcome to the Selling.com API! Our API allows you to access and enrich contact and company data, including emails, names, phone numbers, job titles, and more. This document will guide you through the process of using the API, from getting started with authentication to making your first request.

What Can You Do with the API?

With our API, you can:

Enrich Single Contact or Company Data: Send a set of contact or company details, and we'll return enriched data from our extensive database.
Enrich Multiple Contacts or Companies in Bulk: Submit multiple contacts or companies for enrichment in a single request. The results will be processed in the background, and you can retrieve them once they're ready.

API Requests

To interact with the Selling.com API, you will be making HTTP requests to specific endpoints. Below are the details on how to structure these requests:

Base URL

All API requests should be made to the following base URL: https://api.selling.com/

HTTP Methods

The API supports the following HTTP methods:

GET: Used to retrieve data from the server. This is primarily used for downloading results from bulk enrichment processes.
POST: Used to send data to the server for processing. This is the primary method for submitting single or bulk enrichment requests.

Request Headers

Each request to the API must include the following headers:

Content-Type: Specifies the media type of the resource being sent. For our API, this should be set to: Content-Type: application/json
Authorization: This header must contain your API key in the following format: Authorization: Bearer YOUR_API_KEY

Rate limits

The Selling.com API enforces rate limits to ensure fair usage and optimal performance. The current rate limit status is communicated in the headers of each API response through the rate_limit

field, which indicates the number of allowed requests per minute for the endpoint you are accessing.

If you frequently exceed these rate limits, consider the following strategies:

Optimize Requests: Combine requests or use bulk operations where possible to minimize the number of API calls.
Upgrade Plan: Contact Selling.com support to discuss higher rate limits or custom plans tailored to your specific usage needs.

Exceeding the rate limit will result in a 429 Too Many Requests error. Implementing retry logic with exponential backoff can help manage this scenario effectively.

Authentication

To access the API, you must authenticate each request using an API key. You can generate and manage your API keys in the Selling.com dashboard. For details on how to authenticate your requests, please refer to the Authentication page.

Endpoints Overview

Here’s a quick overview of the available endpoints:

Single Contact Enrichment: Search for a contact using criteria such as first name, last name, company name, and more. Note: At least one combination of linkedin_url
, business_email
, or (first_name
+ last_name
+ company_domain
) or (first_name
+ last_name
+ company_name
) is required in the request.
Bulk Contact Enrichment Submission: Perform a bulk search for multiple contacts using criteria such as first name, last name, company name, and more. The API supports filtering based on available contact data, such as work emails and mobile phones. Additionally, you can pass custom metadata using custom fields. Note: At least one combination of linkedin_url
, business_email
, or (first_name
+ last_name
+ company_domain
) or (first_name
+ last_name
+ company_name
) is required.
Bulk Contact Enrichment Results: This endpoint allows users to retrieve the results of a completed bulk contact enrichment job, which was initiated via the /contacts
endpoint. After submitting a batch of contacts for enrichment, users can access the processed data from this URL. The results will be returned in JSON format and will include details for each contact that was processed. Note that after the expiration date, the results will no longer be available, and the data will be permanently deleted. This endpoint allows users to retrieve the results of a completed bulk contact enrichment job. After submitting a batch of contacts for verification, users can access the processed data from this URL. The results will be available in JSON format and will include details for each contact that was processed.
Single Company Enrichment: Search for companies using criteria such as company name, company website, and more. Note: At least one combination of company_website
or company_name
is required in the request.
Bulk Company Enrichment Submission: Perform a bulk search for multiple companies using criteria such as company name, company website. The API supports filtering based on available company data, such as company website and company names. Additionally, you can pass custom metadata using custom fields. Note: At least one combination of company_website
or company_name
is required.
Bulk Company Enrichment Results: This endpoint allows users to retrieve the results of a completed bulk company enrichment job, which was initiated via the /companies
endpoint. After submitting a batch of companies for enrichment, users can access the processed data from this URL. The results will be returned in JSON format and will include details for each company that was processed. Note that after the expiration date, the results will no longer be available, and the data will be permanently deleted. This endpoint allows users to retrieve the results of a completed bulk company enrichment job. After submitting a batch of companies for verification, users can access the processed data from this URL. The results will be available in JSON format and will include details for each company that was processed.

Error Handling

When making requests to the Selling.com API, you may encounter various errors due to issues such as incorrect request formatting, invalid data, or exceeding rate limits. Each error response will include an HTTP status code and a message to help you understand what went wrong. For a detailed explanation of common errors and how to resolve them, refer to our Error codes page.

If you're experiencing issues with API key authentication, such as receiving a 401 Unauthorized

error, ensure that your API key is correct and formatted properly. For more details on handling API key issues, visit the Authentication page. By understanding and addressing these errors, you can ensure smoother integrations and more reliable interactions with our API.

Legal

By using Selling.com API, you agree to comply with our terms of service and privacy policy. Please review these documents carefully to understand your rights and responsibilities when using the API:

Getting Help

If you have any questions or run into any issues, our support team is here to help. Please contact us at support@selling.com and we’ll get back to you as soon as possible.