Getting started

Piriod API is REST-based with predictable URLs resources-oriented. Accepts Form-data and JSON-encoded request bodies, returns ever JSON-encoded responses and uses standard HTTP response codes.

The Piriod API currently has a single version and has periodic changes in functionality that do not affect the attributes of the different objects that make up the API resources. This documentation explains the use of the different resources and the only source of truth.

You can use the Piriod API in test mode and thus not affect the actual data of the account. The API key is for test mode or real mode.


Learn about concepts

HTTP Response codes

Getting started

To begin the integration with Piriod in your application or website requires that you have a Piriod account and complete the following three steps:

Get your API key

Each Piriod User Account has one API key that allows access to all Piriod Organizations to which said user account has access.

Piriod authenticates your API requests using the API key of your User Account. If you don't send the API key in the request or the API key is wrong, Piriod will return an authentication error.

To obtain your API key you must go to the Account Security section in your User Account.

Get your Piriod Organization ID

Each Piriod Organization has a unique identifier that is related with your Piriod User Account API key.

Piriod authenticates your API requests also using the Piriod Organization ID. If you don't submit the Organization ID or the Organization ID is wrong, Piriod will return an authentication error.

To obtain your API key you must go to the Organizations section in your User Account.

Make an API request

import requests

PIRIOD_API_KEY = '9bba430e7a8a64c2111bf29f497ec58b15906f47' # replace with your api id
PIRIOD_ORGANIZATION_ID = 'acc_8a64c2111bf29fc5' # replace with your organization id

headers = {
    'Authorization': f'Token {PIRIOD_API_KEY}',
    'x-simple-workspace': PIRIOD_ORGANIZATION_ID

payload = {
    'name': 'Acme LLC',
    'address': 'Main St 999',
    'country': 'US',
    'state': 'USAZ',
    'email': '[email protected]',
    'tax_id': '897-56-9831'

r ='{PIRIOD_API_URL}/customers/', json=payload, headers=headers)

Piriod returns a Customer object in response to your API request

    "id": "cus_dl6PTxQnTYy5BHYskV",
    "address": "Main St 999",
    "aggregations": {
        "sales": 0.00,
        "sales_current_period": 0.00,
        "balance": 0.00
    "contacts": [],
    "country": {
        "id": "US",
        "name": "Estados Unidos",
        "name_en": "United states",
        "phone_code": "+1",
        "has_regulation": false,
        "tax_percent": 10
    "currency": "USD",
    "email": "[email protected]",
    "metadata": {},
    "name": "Acme LLC",
    "phone": "",
    "sources": [],
    "state": {
        "id": "USAZ",
        "code": "AZ",
        "name": "Arizona"
    "tax_id": "897-56-9831",
    "tax_settings": {},
    "website": "",
    "created": "2020-10-15T13:26:15.356289-03:00",
    "updated": "2020-10-15T13:26:15.356321-03:00"

If your API request was successful, you can now start integrating the different Piriod API resources. Learn how each resource works by navigating with the left side menu.