IconFinder API v 2.0
v1.0
by speca

IconFinder API v 2.0

NOT OFFICIAL documentation of Iconfinder REST API v2.0

Base URI

https://api.iconfinder.com/v2
Documentation
Overview

This is not official version of Iconfinder REST API v2.0 (beta) Link to Official documentation

All API access is performed over HTTPS and accessed from the api.iconfinder.com domain. The API version 2.0 is accessed under the v2/ subpath. This means that the full base path of all the REST API 2.0 endpoints is https://api.iconfinder.com/v2/, although throughout the documentation this is shortened to /v2/.

Usage of the Iconfinder API version 2.0 is subject to the API terms of service.

The Iconfinder API version 2.0 is currently in beta. We will do our best to avoid breaking changes, but consider the current version unstable at the moment.

HTTP request methods

Where possible, the Iconfinder REST API strives to use appropriate HTTP methods for each action:

Method Action
HEAD Retrieve HTTP header information for one or more resources. Do not rely on this information between requests.
GET Retrieve one or more resources.
POST Create a resource or perform a custom action.
PATCH Partially update a resource.
PUT Completely replace a resource.
DELETE Delete a resource.
Data transmission

All data is sent as UTF-8 encoded JSON identified by the media type application/json.

$ curl -i https://api.iconfinder.com/v2/

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
Content-Length: 194

Data types

Blank fields, ie. fields whose value would be a JSON null, are omitted to keep the response size to a minimum. All timestamps are returned as strings in the ISO 8601 format of arbitrary precision guaranteed to be in UTC:

--
T::Z
--
T::.Z

Summaries and detailed representations

Depending on the endpoint used, either a summary or a detailed representation of a resource will be returned. Generally, listing and search endpoints such as /v2/iconsets will return summaries while resource specific endpoints such as /v2/iconsets/<icon set ID> will return a detailed representation.

While the levels of detail in the representations differ, detailed representations are guaranteed to at least contain the same information in the same structure as summary representations.

HTTP status codes

The following status codes will be sent from the Iconfinder REST API:

Status code Meaning
200 OK Indicates that a request completed successfully and the response contains data.
304 Not Modified The requested resource has not been modified.
400 Bad Request Client request error as described above.
401 Unauthorized Error indicating that the request was performed with invalid or no authorization information.
403 Forbidden Error indicating that the requesting user has a valid set of credentials but does not have access to the given resource.
404 Not Found Error indicating that the requested resource was not found or, alternatively, is not publicly available.

The Iconfinder API version 2.0 uses two different methods of pagination for listing resources. Endpoints with deterministic ordering rely on the last received resource for pagination using the after parameter, while non-deterministic endpoints use the more traditional offset query parameter. See /v2/iconsets and /v2/icons/search respectively for details.

Rate limiting

The Iconfinder API version 2.0 employs strict rate limiting depending on the authentication method. For OAuth 2.0 authenticated requests, you can make up to 5,000 requests per hour for each authorized user. For unautheticated requests, you can make 15 requests per minute.

Rate limits may change during the beta period of Iconfinder API version 2.0.

Not all requests count towards your request rate. Using conditional requests to ease the load on Iconfinder’s servers will only count towards your request rate if a resource has changed.

All responses from the API contain information about the current state of rate limiting:

$ curl -i https://api.iconfinder.com/v2/iconsets

HTTP/1.1 200 OK
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
X-RateLimit-Reset: Mon, 21 Apr 2014 13:27:48 GMT

The special X-RateLimit- headers have the following meaning:

Header name Description
X-RateLimit-Limit Current rate limit for the authentication method used.
X-RateLimit-Remaining Requests remaining until rate limit is reached.
X-RateLimit-Reset Time at which the request counter is reset.

Hitting the wall

If you exceed the request rate limit, the Iconfinder API will return a 429 Too Many Requests response code with the following content:

$ curl -i https://api.iconfinder.com/v2/iconsets

HTTP/1.1 429 Too Many Requests
Date: Mon, 21 Apr 2014 13:27:04 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 0
X-RateLimit-Reset: Mon, 21 Apr 2014 13:27:48 GMT

{
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded"
}

If you need a higher rate limit, please contact support with details about your use case.

Unauthenticated requests with higher rate limit

If you need to make unauthenticated requests to the API with a higher rate limit, you can send the client ID and secret of your API application along with the request. The rate limit will then be the same as for an authenticated request, but the limit is applied at an application level rather than authorization level:

$ curl -i https://api.iconfinder.com/v2/iconsets?client_id=x&client_secret=y

HTTP/1.1 200 OK
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: Mon, 21 Apr 2014 13:27:48 GMT

Only use this method for server-to-server calls. Never share your application’s client secret with anyone or include it in client-side browser code.

Conditional requests

Most API version 2.0 endpoints expose a modification time of resources in the Last-Modified header. The modification time can be used in subsequent requests to the same endpoints using the If-Modified-Since conditional header. If the resource has not been modified between requests, the response status code will be 304 Not Modified.

It is heavily encouraged that server-to-server communications cache responses and use the conditional request mechanisms to reduce the load on the Iconfinder API servers.

Cross Origin Resource Sharing (CORS)

The Iconfinder API version 2.0 supports Cross Origin Resource Sharing (CORS) for AJAX requests, independent of the request origin. This means that the API can be used for unauthenticated AJAX requests:

$ curl -i https://api.iconfinder.com/v2/iconsets

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS
Access-Control-Expose-Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Cross-domain policy

For usage in Flash based applications, the Iconfinder API has a cross-domain policy file allowing full access over HTTPS. See https://api.iconfinder.com/crossdomain.xml for details.

API Methods
Authentication

The Iconfinder API 2.0 offers both a public and a private part of the API. The public part includes the basic functionality, one would experience as a user of Iconfinder without being logged in. The private part of the API includes access to user information, purchases etc. depending on the authorization scope.

There are currently two ways to authenticate. Using a JSON Web Token or using authorization code. Using the web token will allow you to hide the API access from your users - this will require that your account is on an API subscription plan. The authorization code approach lets your users authenticate using their own Iconfinder accounts.

In order to use OAuth 2.0, you need to register an API application, which will be assigned a unique client ID and client secret.

Once you have registered your application, you need to authorize users to be able to access the Iconfinder API version 2.0 as the specific user. The authorization flow between your application and Iconfinder depends on the type of application you’re developing.

It is very important that the client secret is not shared with anyone. When developing an application that uses OAuth 2.0 you should also make sure to use a strong, unique password for your Iconfinder account.

Begin the authorization flow
GET /oauth2/authorize
Obtain access token
GET /oauth2/token
Begin the authorization flow
GET /oauth2/authorize

The method is used to begin the authorization flow

Request parameters

client_id
string optional

your application’s client ID.

Example:
12345
response_type
string required

Response type. Must be code for web application registration.

Example:
code
scope
string optional

Optional comma separated list of scopes. See scopes for more details.

Example:
user
state
string optional

Optional random string used to protect against cross site request forgery attacks.

Example:
random_string

Responses

200 OK

If the user chooses to authorize your application, Iconfinder redirects back to your site at the callback URL you configured for your application when registering it. The URL will include with an intermediate code in the code request parameter as well as the opaque state value if provided. If no code parameter is provided, it means that the user did not choose to authorize your application. If you supplied a state parameter, make sure to validate this to avoid security vulnerabilities.

Obtain access token
GET /oauth2/token

Once you have the intermediate code, it must be exchanged for an access token that will be used for all authenticated requests. Access tokens are obtained at the following URL:

Request parameters

client_id
string required

Your application’s client ID.

client_secret
string required

Your application’s client secret.

code
string required

The intermediate code received from Iconfinder. The result of Begin the authorization flow

grant_type
string required

Grant type. Must be authorization_code to indicate that the token is granted based on an authorization code.

Example:
authorization code

Responses

200 OK

pon successful exchange of the intermediate code, Iconfinder returns a JSON response with the access token and token type issued. Access tokens are guaranteed to be alphanumerical strings of 64 byte lengths:

Body
Object
access_token
string
Example:
mUZrfE9MJySA1YTyGl9HsMjIypWNtl9jqjpfqxMKakdV00Fkh6C38gZkztrtCzWS
token_type
string
Example:
Bearer
JSON Web Token

JSON Web Tokens (JWT) are a standard way of representing security claims between your application and Iconfinder API. A JWT token is simply a signed JSON object which contains information which enables the receiver to authenticate the sender of the request. For more documentation about JWT, see the JWT documentation

Based on an example of a JavaScript based application that makes requests to the Iconfinder API, the sequence diagram will be following:

Generate token server-side

Requesting a new token requires a server-side script that uses the client ID and secret. We have created snippets that can be used as a foundation for your implementation:

Getting a client ID and secret

To generate new tokens you need client ID and secret. You can get these by creating a new API application.

Supported browsers

Authenticating using web tokens requires Cross-Origin Resource Sharing (CORS). To see which users support CORS, please see: http://caniuse.com/#feat=cors

Please find more information for Internet Explorer support on Microsoft’s website

Authors

Content on Iconfinder is always associated with a creator, ie. an entity of some sort, that has created the content. But, because Iconfinder both indexes as well as allows content creators to upload their works, not all content is linked to a known user, who created the content. Instead, indexed content created by someone who is not a user on Iconfinder will be represented as the special “author” type rather than the normal user type.

Get author details
GET /authors/{author id}

Get details about a specific author identified by a unique ID.

Path variables

author id
string required

Author ID

Example:
1

Request body

Author

Responses

200 OK
Example 1
GET https://api.iconfinder.com/v2/authors/2 HTTP/1.1 

Content-Type: application/json

{
  "author_id" : 2,
  "name" : "Everaldo Coelho",
  "iconsets_count" : 12,
  "website_url" : "http://www.everaldo.com/"
}
Categories

Icons can depict virtually anything and have many different use cases, and it can therefore be difficult to find just the icons you need. On Iconfinder, apart from being tagged, icons and icon sets are assigned to at least one of a predefined set of categories to make it easier to find icons based on use case.

Categories on Iconfinder are identified in the API by their unique, humanly readable identifier rather than a numerical ID.

List all categories
GET /categories

List all categories sorted ascendingly by their identifier.

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

Responses

200 OK
Body
Object
total_count
number
Example:
40
categories
Category
Example
GET https://api.iconfinder.com/v2/categories?count=2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "total_count": 40,
    "categories": [
        {
            "identifier": "abstract",
            "name": "Abstract"
        },
        {
            "identifier": "animal",
            "name": "Animals"
        }
    ]
}
Get category details
GET /categories/{category identifier}

t details about a specific category identified by its identifier.

Path variables

category identifier
string required
Example:
halloween

Responses

200 OK
Body
Category
Icons
Get icon details
GET /icons/{icon id}

Get details about a specific icon.

Path variables

icon id
string required

Responses

200 OK
Body
Icon
Example 1
GET https://api.iconfinder.com/v2/icons/11 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "raster_sizes": [
        {
            "size_width": 30,
            "size_height": 30,
            "formats": [
                {
                    "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
                    "download_url": "/icons/233366/formats/png/30/download",
                    "format": "png"
                }
            ],
            "size": 30
        }
    ],
    "styles": [
        {
            "identifier": "outline",
            "name": "Outline"
        }
    ],
    "tags": [
        ""
    ],
    "icon_id": 233366,
    "vector_sizes": [
        {
            "size_width": 60,
            "size_height": 60,
            "formats": [
                {
                    "identifier": "outline",
                    "name": "Outline"
                }
            ],
            "target_sizes": [
                {
                    "0": 30,
                    "1": 60,
                    "2": 120,
                    "3": 180,
                    "4": 240,
                    "5": 480
                }
            ],
            "size": 60
        }
    ],
    "is_premium": true,
    "published_at": "2014-01-24T12:00:14.811Z",
    "containers": [
        {
            "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
            "download_url": "/icons/233366/formats/png/30/download",
            "format": "png"
        }
    ],
    "prices": [
        {
            "currency": "USD",
            "price": 1,
            "license": {
                "url": "https://www.iconfinder.com/licenses/basic",
                "license_id": 71,
                "name": "Basic license",
                "scope": "free"
            }
        }
    ],
    "type": "vector",
    "categories": [
        {
            "identifier": "outline",
            "name": "Outline"
        }
    ],
    "temp": "wefwef",
    "primiti": null
}
show more
List all icons in an icon set
GET /iconsets/{icon set identifier}/icons

Provides a list of all icons in an icon set sorted descendingly by the popularity of the icons.

Path variables

icon set identifier
string required
Example:
3258

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
integer optional

Icon ID of the last icon received. If empty, the count most popular icons are returned.

Responses

200 OK
Body
Object
total_count
number
Example:
1
icons
Icon
Example 1
GET https://api.iconfinder.com/v2/iconsets/3258/icons HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "total_count": 1,
    "icons": {
        "raster_sizes": [
            {
                "size_width": 30,
                "size_height": 30,
                "formats": [
                    {
                        "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
                        "download_url": "/icons/233366/formats/png/30/download",
                        "format": "png"
                    }
                ],
                "size": 30
            }
        ],
        "styles": [
            {
                "identifier": "outline",
                "name": "Outline"
            }
        ],
        "tags": [
            ""
        ],
        "icon_id": 233366,
        "vector_sizes": [
            {
                "size_width": 60,
                "size_height": 60,
                "formats": [
                    {
                        "identifier": "outline",
                        "name": "Outline"
                    }
                ],
                "target_sizes": [
                    {
                        "0": 30,
                        "1": 60,
                        "2": 120,
                        "3": 180,
                        "4": 240,
                        "5": 480
                    }
                ],
                "size": 60
            }
        ],
        "is_premium": true,
        "published_at": "2014-01-24T12:00:14.811Z",
        "containers": [
            {
                "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
                "download_url": "/icons/233366/formats/png/30/download",
                "format": "png"
            }
        ],
        "prices": [
            {
                "currency": "USD",
                "price": 1,
                "license": {
                    "url": "https://www.iconfinder.com/licenses/basic",
                    "license_id": 71,
                    "name": "Basic license",
                    "scope": "free"
                }
            }
        ],
        "type": "vector",
        "categories": [
            {
                "identifier": "outline",
                "name": "Outline"
            }
        ],
        "temp": "wefwef",
        "primiti": null
    }
}
show more
Search for icons
POST /icons/search

Search through icons by various criteria. The returned list of icons is ordered descendingly by popularity.

Request parameters

query
string required

Search query

Example:
facebook
offset
number optional

Result offset. Starts from 0, resulting in the first count icons being returned.

Example:
1
size_minimum
number optional

Minimum icon size to include in search result.

Default:
0
Example:
24
size_maximum
number optional

Maximum icon size to include in search result.

Default:
512
category
string optional

icon category

Example:
internet
style
string optional

icon style

Example:
contemporary
count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Object
total_count
string
Example:
442
icons
Icon
Example 1
POST https://api.iconfinder.com/v2/icons/search?query=facebook HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "total_count": "442",
    "icons": {
        "raster_sizes": [
            {
                "size_width": 30,
                "size_height": 30,
                "formats": [
                    {
                        "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
                        "download_url": "/icons/233366/formats/png/30/download",
                        "format": "png"
                    }
                ],
                "size": 30
            }
        ],
        "styles": [
            {
                "identifier": "outline",
                "name": "Outline"
            }
        ],
        "tags": [
            ""
        ],
        "icon_id": 233366,
        "vector_sizes": [
            {
                "size_width": 60,
                "size_height": 60,
                "formats": [
                    {
                        "identifier": "outline",
                        "name": "Outline"
                    }
                ],
                "target_sizes": [
                    {
                        "0": 30,
                        "1": 60,
                        "2": 120,
                        "3": 180,
                        "4": 240,
                        "5": 480
                    }
                ],
                "size": 60
            }
        ],
        "is_premium": true,
        "published_at": "2014-01-24T12:00:14.811Z",
        "containers": [
            {
                "preview_url": "https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png",
                "download_url": "/icons/233366/formats/png/30/download",
                "format": "png"
            }
        ],
        "prices": [
            {
                "currency": "USD",
                "price": 1,
                "license": {
                    "url": "https://www.iconfinder.com/licenses/basic",
                    "license_id": 71,
                    "name": "Basic license",
                    "scope": "free"
                }
            }
        ],
        "type": "vector",
        "categories": [
            {
                "identifier": "outline",
                "name": "Outline"
            }
        ],
        "temp": "wefwef",
        "primiti": null
    }
}
show more
Icon sets

All icons on Iconfinder are organized into sets created by a specific author. Sets share a set of common attributes, such as licensing, pricing etc.

List all public icon sets
GET /iconsets

List all public icon sets in descending order of when they were published.

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
Example 1
GET https://api.iconfinder.com/v2/iconsets HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "total_count": "",
    "iconsets": [
        {
            "styles": [
                {
                    "identifier": "outline",
                    "name": "Outline"
                }
            ],
            "icons_count": 50,
            "author": {
                "username": "webalys",
                "user_id": 40097,
                "name": "Vincent Le Moign",
                "iconsets_count": 74,
                "company": "Webalys",
                "is_designer": true,
                "location": "Hong Kong",
                "social_twitter": "webalys",
                "social_dribbble": "webalys",
                "website_url": "http://www.webalys.com/"
            },
            "is_premium": true,
            "published_at": "2014-05-29T11:38:43.852Z",
            "prices": [
                {
                    "currency": "USD",
                    "price": 1,
                    "license": {
                        "url": "https://www.iconfinder.com/licenses/basic",
                        "license_id": 71,
                        "name": "Basic license",
                        "scope": "free"
                    }
                }
            ],
            "identifier": "coloricons-5",
            "type": "vector",
            "iconset_id": 5411,
            "categories": [
                {
                    "identifier": "outline",
                    "name": "Outline"
                }
            ],
            "name": "Coloricons 5"
        }
    ]
}
show more
List icon sets of a specific style
GET /styles/{style identifier}/iconsets

List public icon sets of a specific style in descending order of when they were published.

Path variables

style identifier
string required

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
List icon sets in a category
GET /categories/{category identifier}/iconsets

List public icon sets in a category in descending order of when they were published.

Path variables

category identifier
string required
Example:
shopping

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
List a user's icon sets
GET /v2/users/{userid or username}/iconsets

List all public icon sets owned by a specific user in descending order of when they were published.

Path variables

userid or username
string required

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
Example 1
GET https://api.iconfinder.com/v2/v2/users/%username%/iconsets HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "total_count": "",
    "iconsets": [
        {
            "styles": [
                {
                    "identifier": "outline",
                    "name": "Outline"
                }
            ],
            "icons_count": 50,
            "author": {
                "username": "webalys",
                "user_id": 40097,
                "name": "Vincent Le Moign",
                "iconsets_count": 74,
                "company": "Webalys",
                "is_designer": true,
                "location": "Hong Kong",
                "social_twitter": "webalys",
                "social_dribbble": "webalys",
                "website_url": "http://www.webalys.com/"
            },
            "is_premium": true,
            "published_at": "2014-05-29T11:38:43.852Z",
            "prices": [
                {
                    "currency": "USD",
                    "price": 1,
                    "license": {
                        "url": "https://www.iconfinder.com/licenses/basic",
                        "license_id": 71,
                        "name": "Basic license",
                        "scope": "free"
                    }
                }
            ],
            "identifier": "coloricons-5",
            "type": "vector",
            "iconset_id": 5411,
            "categories": [
                {
                    "identifier": "outline",
                    "name": "Outline"
                }
            ],
            "name": "Coloricons 5"
        }
    ]
}
show more
List an author's icon sets
GET /authors/{author id}/iconsets

List all public icon sets owned by a specific author in descending order of when they were published.

Path variables

author id
string required
Example:
611

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
List an authenticated user's icon sets
GET /user/iconsets

List all public icon sets owned by the authenticated user in descending order of when they were published.

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

premium
string optional

Filter premium icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are premium or not.

0

or false Only include icon sets that are not premium, ie. may require purchasing a license for specific use cases but are not sold directly on the Iconfinder marketplace.

1

or true Only include premium icon sets, that are sold directly on the Iconfinder marketplace.

vector
string optional

Filter vector icon sets.

Enumeration:
all

or empty value Include all icon sets no matter if they are vector or raster icon sets.

0

or false Only include raster icon sets in the result.

1

1 or true Only include vector icon sets in the result.

license
string optional

Filter by license scope.

Enumeration:
none

Include all icon sets no matter the license

commercial

Only include icon sets that can be used commercially, but may require attribution or be restricted by other licensing concerns

commercial-nonattribution

Only include icon sets that be used commercially without any attribution requirements

Responses

200 OK
Body
Array of Iconset
Example 1
GET https://api.iconfinder.com/v2/user/iconsets HTTP/1.1 

HTTP/1.1 200 OK
Get icon set details
GET /iconsets/{icon set id or identifier}

Get details about a specific icon set.

Path variables

icon set id or identifier
string required
Example:
cat-power-premium

Responses

200 OK
Body
Iconset
Example 1
GET https://api.iconfinder.com/v2/iconsets/cat-power-premium HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "styles": [
        {
            "identifier": "outline",
            "name": "Outline"
        }
    ],
    "icons_count": 50,
    "author": {
        "username": "webalys",
        "user_id": 40097,
        "name": "Vincent Le Moign",
        "iconsets_count": 74,
        "company": "Webalys",
        "is_designer": true,
        "location": "Hong Kong",
        "social_twitter": "webalys",
        "social_dribbble": "webalys",
        "website_url": "http://www.webalys.com/"
    },
    "is_premium": true,
    "published_at": "2014-05-29T11:38:43.852Z",
    "prices": [
        {
            "currency": "USD",
            "price": 1,
            "license": {
                "url": "https://www.iconfinder.com/licenses/basic",
                "license_id": 71,
                "name": "Basic license",
                "scope": "free"
            }
        }
    ],
    "identifier": "coloricons-5",
    "type": "vector",
    "iconset_id": 5411,
    "categories": [
        {
            "identifier": "outline",
            "name": "Outline"
        }
    ],
    "name": "Coloricons 5"
}
show more
Licenses
Get license details
GET /licenses/{license id}

Get details about a specific license by its unique ID.

Path variables

license id
string required

Responses

200 OK
Body
License
Example 1
GET https://api.iconfinder.com/v2/licenses/71 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "url": "https://www.iconfinder.com/licenses/basic",
    "license_id": 71,
    "name": "Basic license",
    "scope": "free"
}
Styles

Icons – like any other pieces of design – have very distinct styles and follow trends. Therefore, icons and icon sets on Iconfinder are assigned at least one of a set of predefined styles to make it easier for users to find icons and icon sets that will fit their style needs for a given use case. i Styles on Iconfinder are identified in the API by their unique, humanly readable identifier rather than a numerical ID.

List all styles
GET /styles

List all styles sorted ascendingly by their identifier.

Request parameters

count
integer optional

Number of icon sets to include in the result.

Min: 1
Max: 100
Default:
100
after
string optional

identifier of the last entity received. If empty, the count first categories are returned.

Responses

200 OK
Body
Object
styles
Object
identifier
string
Example:
3d
name
string
Example:
3D
total_count
number
Example:
9
List styles
GET https://api.iconfinder.com/v2/styles HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "styles": [
        {
            "identifier": "3d",
            "name": "3D"
        },
        {
            "identifier": "cartoon",
            "name": "Cartoon"
        },
        {
            "identifier": "flat",
            "name": "Flat"
        },
        {
            "identifier": "glyph",
            "name": "Glyph"
        },
        {
            "identifier": "handdrawn",
            "name": "Handdrawn"
        },
        {
            "identifier": "outline",
            "name": "Outline"
        },
        {
            "identifier": "photorealistic",
            "name": "Photorealistic"
        },
        {
            "identifier": "pixel",
            "name": "Pixel"
        },
        {
            "identifier": "smooth",
            "name": "Smooth"
        }
    ],
    "total_count": 9
}
show more
Get style details
GET /styles/{style identifier}

Get details about a specific style identified by its identifier.

Path variables

style identifier
string required

Responses

200 OK
Body
Object
identifier
string
Example:
flat
name
string
Example:
Flat
Get flat style details
GET https://api.iconfinder.com/v2/styles/flat HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "identifier" : "flat",
  "name" : "Flat"
}
Users
Get user details
GET /users/{userid or username}

Get details about a specific user.

Path variables

userid or username
string required
Example:
webalys

Responses

200 OK
Body
User
Example
GET https://api.iconfinder.com/v2/users/webalys HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "username" : "webalys",
  "user_id" : 40097,
  "name" : "Vincent Le Moign",
  "iconsets_count" : 74,
  "company" : "Webalys",
  "is_designer" : true,
  "location" : "Hong Kong",
  "social_twitter" : "webalys",
  "social_dribbble" : "webalys",
  "website_url" : "http://www.webalys.com/"
}
Responses
400 Bad Request
Applied to all operations

The request was malformed.

Body
Error model
Examples
{
    "code": "bad_request",
    "message": "The request was malformed."
}
400 invalid_<parameter>
Applied to all operations

The request was malformed. The query parameter parameter contains an invalid value.

Body
Error model
401 bad_credentials
Applied to all operations

Invalid credentials were used to authenticate the request.

Body
Error model
403 permission_denied
Applied to all operations

Permission to the requested resource was denied. This often means that a request should have been authenticated but wasn’t. dispatched to clean up the mess immediately!

Body
Error model
403 insufficient_permissions
Applied to all operations

The authentication used does not have the required permissions to access the requested resource. Make sure the authentication was performed with the necessary scope.

Body
Error model
403 not_purchased
Applied to all operations

The premium resource you’re trying to access has not been purchased by the authenticated user.

Body
Error model
404 not_found
Applied to all operations

The requested resource does not exist or is not publicly available.

Body
Error model
429 rate_limit_exceeded
Applied to all operations

API request rate limit exceeded. See rate limiting.

Body
Error model
500 server_error
Applied to all operations

An internal server error occured. This shouldn’t happen, and robots will be dispatched to deal with it immediately.

Body
Error model
Data Reference
Author

See Format Model bold

Object
author_id
number
Example:
2
name
string
Example:
Everaldo Coelho
iconsets_count
number
Example:
12
website_url
string
Example:
http://www.everaldo.com/
Methods: Get author details
Category
Object
identifier
string
Example:
halloween
name
string
Example:
Halloween
Methods: Get category details List all categories
Format
Object
preview_url
string
Example:
https://cdn1.iconfinder.com/data/icons/streamline-business-finance/60/cell-0-12-30.png
download_url
string
Example:
/icons/233366/formats/png/30/download
format
string
Example:
png
Types: Icon
IdAndName

Name - Description pair

Object
identifier
string
Example:
outline
name
string
Example:
Outline
Types: Icon Iconset
License
Object
url
string
Example:
https://www.iconfinder.com/licenses/basic
license_id
number
Example:
71
name
string
Example:
Basic license
scope
string
Example:
free
Methods: Get license details
Types: Price
Price
Object
currency
string
Example:
USD
price
number
Example:
1
license
License
Types: Icon Iconset
Icon
Object
raster_sizes
Array
Object
size_width
number
Example:
30
size_height
number
Example:
30
formats
Array of Format
size
number
Example:
30
styles
Array of IdAndName
tags
Array of string
Example: 
interest
icon_id
number
Example:
233366
vector_sizes
Array
Object
size_width
number
Example:
60
size_height
number
Example:
60
formats
Array of IdAndName
target_sizes
Array
Object
0
number
Example:
30
1
number
Example:
60
2
number
Example:
120
3
number
Example:
180
4
number
Example:
240
5
number
Example:
480
size
number
Example:
60
is_premium
boolean
Example:
true
published_at
string
Example:
2014-01-24T12:00:14.811Z
containers
Array of Format
prices
Array of Price
type
string
Example:
vector
categories
Array of IdAndName
temp
Test enum

test enums

primiti
unknown
show more
Methods: Get icon details List all icons in an icon set Search for icons
Iconset
Object
styles
Array of IdAndName
icons_count
number
Example:
50
author
User
is_premium
boolean
Example:
true
published_at
string
Example:
2014-05-29T11:38:43.852Z
prices
Array of Price
identifier
string
Example:
coloricons-5
type
string
Example:
vector
iconset_id
number
Example:
5411
categories
Array of IdAndName
name
string
Example:
Coloricons 5
show more
Methods: Get icon set details List a user's icon sets List all public icon sets List an authenticated user's icon sets List an author's icon sets List icon sets in a category List icon sets of a specific style
User

[See docs](doc://Data transmission sdfwef)

Object
username
string
Example:
webalys
user_id
number
Example:
40097
name
string
Example:
Vincent Le Moign
iconsets_count
number
Example:
74
company
string
Example:
Webalys
is_designer
boolean
Example:
true
location
string
Example:
Hong Kong
social_twitter
string
Example:
webalys
social_dribbble
string
Example:
webalys
website_url
string
Example:
http://www.webalys.com/
show more
Methods: Get user details
Types: Iconset
SearchforiconsRequest

ewf

Object
coordinates
unknown
favorited
boolean
Example:
false
truncated
boolean
Example:
false
created_at
string
Example:
Wed Aug 29 17:12:58 +0000 2012
id_str
string
Example:
240859602684612608
entities
unknown
in_reply_to_user_id_str
unknown
contributors
unknown
text
string
Example:
Introducing the Twitter Certified Products Program: https://t.co/MjJ8xAnT
retweet_count
number
Example:
121
in_reply_to_status_id_str
unknown
id
number
Example:
240859602684612600
geo
unknown
retweeted
boolean
Example:
false
possibly_sensitive
boolean
Example:
false
in_reply_to_user_id
unknown
place
unknown
user
unknown
in_reply_to_screen_name
unknown
source
string
Example:
<a href="http://sites.google.com/site/yorufukurou/" rel="nofollow">YoruFukurou</a>
in_reply_to_status_id
unknown
show more
Error model
Object
code
string
Example:
not_found
message
string
Example:
Not found
Responses: Bad Request bad_credentials insufficient_permissions invalid_<parameter> not_found not_purchased permission_denied rate_limit_exceeded server_error
IconSet Envelope

Response wrapper object

Object
total_count
string
iconsets
Object data_container

Data container

Methods: List a user's icon sets List all public icon sets List an authenticated user's icon sets List an author's icon sets List icon sets in a category List icon sets of a specific style
Test enum

ewfwef

string
Enumeration:
wefwef

value sescription!

Types: Icon