---
title: "API Reference"
description: "This section provides important information related to the authentication models that are currently enabled to access the Fabrick Platform APIs."
url: "https://docs.fabrick.com/en/fabrick-platform/introduction/fabrick-platform-api-reference/"
language: "en"
---

# API Reference

## Authentication

This section provides important information related to the authentication models that are currently enabled to access the Fabrick Platform APIs. 

You should refer to the **Direct Access** authentication model if you are interested in accessing *your own* products/services (e.g., you are integrating into your ERP the access to your company cash account).

You should refer to the **Personified Access** authentication model if you are a system integrator and/or a technical third party that provides software on behalf of one or more customers.

### Direct Access

The Direct Access authentication model is required whenever API calls are requested by the same subject that is the owner of the product/service on which operations should be executed.\
For example, whenever a company develops a new software to access its own product/services, such as its cash accounts or its corporate credit cards, the Direct Access authentication model must be used.

In this scenario you will be required to manage a single security element:

- **API Key** An application key, in the form of a base-64 alphanumeric string, like `4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS`.

APIs may be invoked directly since the authentication is implicitly provided by your APIKey and IP whitelist.\
Each API request must be then issued by specifing the following common headers:

```html
Content-Type: 'application/json'
Auth-Schema: 'S2S'
Api-Key: '{Your APIKey}'
```

### Personified Access

This scenario requires the interaction of your system with the Fabrick Platform Authentication APIs before engaging any interaction with other APIs, in order to obtain an AuthToken that allows you to provide proof of authentication that you have been granted to the operation you are about to perform.

In this scenario you will be required to manage two security elements:

- **APIKey** An application key, in the form of a 34-byte base-64 alphanumeric string, like `4MSI5FGCXK5UVV2U487A08OZH4NHCHTKS`.
- **AuthToken** A personification token, in the form of a 256-byte base-64 alphanumeric string, like `634a3b26dd4f...2cPWqcZVUfG01D2`.

Each API request must be then issued by specifing the following common headers:

```html
Content-Type: 'application/json'
Auth-Schema: 'S2S-AUTH'
Auth-Token: '{PersonificationToken}'
```

Please refer to the Affiliation section for more details.

## Response Structure

This section provides important information about the common structure of each endpoint response that you will get by invoking Fabrick Platform APIs.

Please remember that in the technical documentation of each endpoint you will find only the specific information related to the structure of the response payload element; the general response structure is implicitly assumed as documented in this section.

The reference to the response structure distinguishes among the API version to document each version response structure: please be sure to refer to the correct version number.

### API Version 5.x

```json
{  
    "status": "OK",
    "errors": null,
    "warnings": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}], // optional
        "pagination": { // optional with "list"
            "resultCount": <number>,
            "pageCount": <number>,
            "offset": <number>,
            "limit": <number>
        }
    }
}
```

The `status` field contains one of the following status codes:

- `OK` If the response contains payload.
- `KO` If the response contains one or more errors.

The `errors` array may contain info related to error handling (see below for details). The `warnings` array may contain info related to warning handling (see below for details).

The `payload` object typically contains the response data.

The `payload.list` array typically contains one or more result elements.

The `payload.pagination` object is optional and contains the following fields:

- `pageCount` The total number of pages, assuming each page contains "limit" number of results.
- `resultCount` The total number of results.
- `offset` The positional index of the first element provided in the response.
- `limit` The number of elements provided in the response.

```json
{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "warnings": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "payload": null
}
```

Both the `errors` and `warnings` arrays contain one or more elements with the following structure.

The `code` field contains an error/warning unique code. The `description` field contains a textual description related to the error/warning. The `params` field is a string optionally containing the name of the input parameter affected by the reported error/warning.

### API Version 4.x

```json
{  
    "status": "OK",
    "errors": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}], // optional
        "pagination": { // optional with "list"
            "resultCount": <number>,
            "pageCount": <number>,
            "offset": <number>,
            "limit": <number>
        }
    }
}
```

The `status` field contains one of the following status codes:

- `OK` If the response contains payload.
- `KO` If the response contains one or more errors.
- `PENDING` If the response requires further interaction.

The `errors` array may contain info related to error handling (see below for details).

The `payload` object typically contains the response data.

The `payload.list` array typically contains one or more result elements.

The `payload.pagination` object is optional and contains the following fields:

- `pageCount` The total number of pages, assuming each page contains "limit" number of results.
- `resultCount` The total number of results.
- `offset` The positional index of the first element provided in the response.
- `limit` The number of elements provided in the response.

```json
{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": "<string>"
        }
    ],
    "payload": null
}
```

The `errors` array contains one or more elements with the following structure.

The `code` field contains an error unique code. The `description` field contains a textual description related to the error. The `params` field is a string optionally containing the name of the input parameter affected by the reported error.

### API Version 3.x

```json
{  
    "status": "OK",
    "errors": null,
    "payload": {
        <resource-model>

        OR

        "list": [{<resource-model>}]
    }
}
```

The `status` field contains one of the following status codes:

- `OK` If the response contains payload.
- `KO` If the response contains one or more errors.
- `PENDING` If the response requires further interaction.

The `errors` array may contain info related to error handling (see below for details).

The `payload` object typically contains the response data.

The `payload.list` array typically contains one or more result elements.

Pagination is not supported.

```json
{  
    "status": "KO",
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": ["<string>"]
        }
    ],
    "payload": null
}
```

The `errors` array contains one or more elements with the following structure.

The `code` field contains an error unique code. The `description` field contains a textual description related to the error. The `params` field is an array of strings eventually containing the name(s) of the input parameters affected by the reported errors.

### API Version 2.x

```json
{  
    "status": {
        "code": "OK",
        "description": ""
    },
    "errors": null,
    "payload": [<resource-model>, ...]
}
```

The `status.code` field contains one of the following status codes:

- `OK` If the response contains payload.
- `KO` If the response contains one or more errors.
- `PENDING` If the response requires further interaction.

The `status.description` field contains a textual description of the response code.

The `errors` array may contain info related to error handling (see below for details).

The `payload` array typically contains the response data.

Lists and pagination are not supported.

```json
{  
    "status": {
        "code": "KO",
        "description": ""
    },
    "errors": [
        {
            "code": "<string",
            "description": "<string>",
            "params": ["<string>"]
        }
    ],
    "payload": null
}
```

The `errors` array contains one or more elements with the following structure.

The `code` field contains an error unique code. The `description` field contains a textual description related to the error. The `params` field is an array of strings eventually containing the name(s) of the input parameters affected by the reported errors.

### API Version 1.x

```json
{  
    "status": {
        "code": "OK",
        "description": ""
    },
    "error": null,
    "payload": [<resource-model>, ...]
}
```

The `status.code` field contains one of the following status codes:

- `OK` If the response contains payload.
- `KO` If the response contains one or more errors.

The `status.description` field contains a textual description of the response code.

The `errors` object may contain info related to error handling (see below for details).

The `payload` array typically contains the response data.

Lists and pagination are not supported.

```json
{  
    "status": {
        "code": "KO",
        "description": ""
    },
    "error": {
        "description": "<string>"
    },
    "payload": null
}
```

The `error.description` field contains a textual description of the error.

## Pagination

Pagination is available for endpoints in v4.0+.

```http
<HTTP VERB> <URI>?offset={offset}&limit={limit}&pagination={pagination}
```

If available, the request for pagination is managed through query parameters.

The `offset` parameter is the 0-based positional index of the first element to be provided in the response. A positive integer is expected; default value is 0. Additional information:

- If `offset >= resultCount` the response is always empty (fetching over last available result).
- If `offset < 0` an HTTP-400 Bad Request error is returned (a positive integer is expected).

The `limit` parameter is the number of elements to be provided in the response. A positive integer is expected; default value is 20. Additional information:

- If `limit < 0` an HTTP-400 Bad Request error is returned (a positive integer is expected).

The `pagination` parameter is a boolean flag used to request the `pagination` element in the response. Default value is `true`.

```json
{  
    ...  
    "pagination": {  
        "pageCount": 50,  
        "resultCount": 495,  
        "offset": 0,  
        "limit": 10  
    }  
}
```

The `pageCount` field contains the total number of pages, assuming each page contains `limit` number of elements.

The `resultCount` field contains the total number of result elements.

The `offset` field contains the positional index of the first element provided in the response.

The `limit` field contains the maximum number of elements to be expected in the response.

## Data Types

The Fabrick Platform APIs assume the following data types and formats.

| Data Type    | Default Format             | Example                       | Notes                                                    |
| ------------ | -------------------------- | ----------------------------- | -------------------------------------------------------- |
| String       | -                          | `"A string"`                  | -                                                        |
| Number       | `#.#`                      | `12.56`                       | -                                                        |
| Boolean      | `true` - `false`           | `true`                        | -                                                        |
| Object       | `{...}`                    | `{"stringField": "A string"}` | -                                                        |
| Array        | `[...]`                    | `["elem1", "elem2"]`          | -                                                        |
| Date         | `YYYY-MM-DD`               | `2019-03-31`                  | Follows ISO 8601 standard, with `X-Time-Zone` header     |
| Datetime     | `YYYY-MM-DDThh:mm:ss.sssZ` | `2019-03-31T12:49:25.451Z`    | Follows ISO 8601 standard                                |
| Timestamp    | `[0-9]{13}`                | `1550230023518`               | Milliseconds since Unix epoch (Jan 1, 1970 00:00:00 UTC) |
| CountryCode  | `[A-Z]{2}`                 | `IT`                          | Follows ISO 3166-1 alpha 2 standard                      |
| CurrencyCode | `[A-Z]{3}`                 | `EUR`                         | Follows ISO 4217 standard                                |