menu
Particeep

Particeep Plug API

Introduction

Overview

The Particeep Plug API is organized around REST . Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

To make the API as explorable as possible, the test API keys that are directly embedded allow you to query routes related to financial products and their management. Requests made with these test mode credentials have no impact on real financial products and incur no cost.
This page allows you to test the API in a sandbox environment. It's shared with other people and reset from time to time.

This API service is provided by Particeep

Questions, Concerns, Bug Reports

We'll occasionally send announcement emails to all developers with registered apps. You should follow @particeep for frequent updates. And please, send your feedback via our contact page

Access

In its current state, the API lends you access to the test environment, and you will be able to query routes with the identity of a "fictional" broker managing their products. No further configuration is required to do so.

Send us an email at support@particeep.com or call us to get your API key

HTTP / HTTPS

All endpoints are available over HTTPS only.

In order to tinker with those routes, you may use this public key and secret.

Public access
key d78de722-868a-4c1e-b5ad-2e00bc4897a6
secret f289f887-7d3a-4a4a-b3d4-985ac57225cf
This is a shared environnement. When you use this test key, everyone may access and change your data.

Authentification

All access to the API must be authenticated.
We use specific headers :

  • Date: the date of the request in the iso 8601 format. e.g: 2015-10-19T11:04:18Z
  • Content-Type: standard header
  • Authorization: a hash formed with the input data of the request (more detail below)
  • nonce: a random string to enable idempotence
  • Broker_id: your api key
  • Broker_user_id: should be empty for server to server request
  • X-Requested-With: the name of your application

If you send an API request that follow an action made by a user, you can setup these header to allow a better audit. Otherwise put data related to your application or let them empty (they are still required).

How to build the Authorization's header

Follow these steps to build your Authorization's header. This is provided with an example of implementation in Java.

  • Canonize your header :
    • you take all the header above
    • filter out the following headers : Authorization, Date, Content-Type
    • sort them alphabetically
    • build a string with the value of each header on one line each
    • public static String canonize(Map<String, String> headers) {
    return headers.entrySet().stream()
      .filter(x -> !x.getKey().equalsIgnoreCase("Date") && !x.getKey().equalsIgnoreCase("Content-Type"))
      .sorted(Map.Entry.comparingByKey())
      .map(x -> x.getValue())
      .collect(Collectors.joining("\n"));
}
  • Build the string to sign
    • String toSign = String.join("\n",
  "GET",            // HTTP verbe
  "",               // not used for now
  content_type,     // value of the "Content-Type" header
  date,             // value of the "Date" header
  canonize_header   // value computed in the previous step
)
  • add secret and key to the resulting string and get a list of bytes from it in UTF-8 format.
    •             String message = String.join("", apiSecret, apiKey, toSign);
            byte[] messageBytes = message.getBytes("UTF-8");
  • Get a list of bytes from your APISecret in UTF-8 format.
    • byte[] secretBytes = apiSecret.getBytes("UTF-8")
  • Sign 'messageBytes' with 'secretBytes' using SHA1.
    • import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

Mac mac = Mac.getInstance("HmacSHA1");
SecretKeySpec signingKey = new SecretKeySpec(secretBytes, "HmacSHA1");
mac.init(signingKey);
byte[] result = mac.doFinal(messageBytes);
  • Encode the resulting bytes in hexadecimal format.
    • char[] HEX_CHARS = "0123456789ABCDEF".toCharArray();

int len = result.length;
char[] hexChars = new char[len * 2];

for (int charIndex = 0, startIndex = 0; charIndex < hexChars.length;) {
int bite = result[startIndex++] & 0xff;
hexChars[charIndex++] = HEX_CHARS[bite >> 4];
hexChars[charIndex++] = HEX_CHARS[bite & 0xf];
}

// We use lowercase
String sign = new String(hexChars).toLowerCase();
  • Encode the bytes of the result in base 64.
    • import org.apache.commons.codec.binary.Base64;
String signature = new String(Base64.encodeBase64(sign.getBytes("UTF-8")));
  • Concat all results like this: PTP apiKey:signature to get your Authorization header
    • String authorization_header = "PLG " + apiKey + ":" + signature;

If you don't provide the correct authentification information, you will get a 403 - Forbidden response.

Data Format

Response Format

Unless specified otherwise, all responses are of type application/json .

Data Format

  • We use UTF-8 encoding for everything.
  • The content-type of requests must be application/json
  • All dates must be endoded in iso 8601 format.
  • In every response we always use UTC timezone, e.g. 2015-08-10T08:50:00Z
  • In every request you're free to use the timezone you want as long as it's specified in the format, e.g. 2015-08-10T08:50:00+01

Password security

Regarding the security of your data, everything related to Users' passwords is encrypted.
We never know the passwords of your users.

Errors

Particeep uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Particeep's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, so there may be some exception. If a return code is not clear, please contact us

HTTP status code summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
403 - Forbidden You don't have the right to do this
404 - Not Found The requested resource doesn't exist.
500, 502, 503, 504 - Server Errors Something went wrong on Particeep's end. (These are rare.)

Error format

When the api responds with an error, the body of the response contains explanation about the error.
These errors are most of the time explicit and returned in plain text. Once again, if you do not understand the meaning of an error, let us know.

Here is an example of a JSON with the error format. 

{
  "errors": [
    "That subscription doesn't exist."
  ]
}

Pagination

A lot of endpoint return list of entities. Theses list are always paginate the same way : by using limit and offset parameters.

Parameters
limit default: 30 The number of element you want to retrieve. Usually the number of element in a given page
offset default: 0 The number of element you want to drop. For instance you have 30 element per page and you want to retrive the third page you will use : limit = 30, offset = 60

The response use this json envelop. It is your job to know which offset and limit you have used.
total_size is the total amount of element available for your request.
For instance you query your users with default parameters, "total_size": 1230 indicate you have 1 230 users and the response will contains the first 30 users in the data array. 

{
  "total_size": 1230, // total number of element available
  "data": [
    {
      "id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
      "created_at": "2015-08-10T00:00:00Z",
      ... other fields of the object
    },
    {
      "id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
      "created_at": "2015-08-10T00:00:00Z",
      ... other fields of the object
    },
    ...
  ]
}

Endpoints