API documentation

← Towards the developers space

Data encoding and request signature

Build an API request

An API request is an HTTP request sent to the URL:

  • [method]: The API method you want to call.
  • [format]: The response format you wish. Format is optional, default value is json.
  • The API allows sending parameters using GET and POST.
    All the methods implying modification of data (add/edit/delete) always use POST.

Data encoding

All data must be encoded in UTF-8 format.

We try to detect if you use another charset. So we attempt to convert to UTF-8 (but it's better to use UTF-8 encoding.).

Request signature

Some API methods require signature. So ipernity can check whether your application is the requester or not.
To sign a request, you must get an API key (api_key) and a secret code (secret). This secret code must be kept ... secret!.

The request signature corresponds to the md5 of a string composed of the following parameters concatenated each other without spaces:

  • alphabetical ordered parameters followed by their values,
  • the called method,
  • your API key secret.

For example, if you wish to call doc.tags.add method with the following parameters:

  • api_key: 6fa87ba500002712bd4eed6020f3bd72
  • secret: e9a599f0cf6ce193
  • doc_id: 1234
  • keywords: easy
String to be signed will be:
and its md5:

The signed API request will be:


Missing or invalid signature will cause 104 (missing) or 105 (invalid) error.

Did you know? We propose a signature calculation wizard.

Authorization link signature

Calculation of an authorization link signature is made like calculation of a request signature without specifying an API method name.

For instance, we like to ask the authorization to access in read only mode the user's contact list, here are the parameters to sign:

  • api_key: 6fa87ba500002712bd4eed6020f3bd72
  • secret: e9a599f0cf6ce193
  • perm_network: read
So the string to sign is:
and its md5:
Here is the authorization link:

Learn more about authentication for Web applications or authentication for desktop applications.