Skip to main content
POST
/
customers
Create customer
curl --request POST \
  --url https://api.piriod.com/customers/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-simple-workspace: <x-simple-workspace>' \
  --data '
{
  "name": "<string>",
  "address": "<string>",
  "country": "<string>",
  "state": 123,
  "currency": "<string>",
  "email": "jsmith@example.com",
  "phone": "<string>",
  "website": "<string>",
  "zip_code": "<string>",
  "manager": "<string>",
  "reference": "<string>",
  "tax_id": "<string>",
  "tax_settings": {},
  "metadata": {},
  "send_invoices": true,
  "send_collections": true,
  "send_vouchers": true
}
'
{
  "name": "<string>",
  "address": "<string>",
  "country": {
    "id": "CL",
    "name": "Chile",
    "code": "+56",
    "has_regulation": true,
    "currencies": [
      "CLP"
    ]
  },
  "state": {
    "id": 123,
    "name": "<string>",
    "country": "CL"
  },
  "id": "cus_01H8XYZ123ABC",
  "currency": "CLP",
  "email": "jsmith@example.com",
  "phone": "<string>",
  "website": "<string>",
  "zip_code": "<string>",
  "manager": "<string>",
  "reference": "<string>",
  "tax_id": "<string>",
  "tax_settings": {},
  "metadata": {},
  "send_invoices": true,
  "send_collections": true,
  "send_vouchers": true,
  "status": "active",
  "contacts": [
    {
      "name": "<string>",
      "email": "jsmith@example.com",
      "id": "con_01H8XYZ123ABC",
      "customer": "<string>",
      "orgunit": "<string>",
      "phone": "<string>",
      "invoicing": true,
      "collections": true,
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z"
    }
  ],
  "sources": [
    "<string>"
  ],
  "aggregations": {
    "sales": 123,
    "sales_current_period": 123,
    "balance": 123
  },
  "test_mode": true,
  "created": "2023-11-07T05:31:56Z",
  "updated": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://piriod-d406ac55.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Use header Authorization: Token <api_token>. API tokens are obtained from the Piriod dashboard.

Headers

​
x-simple-workspace
string
required

Workspace (account) identifier. Required for every request.

​
x-piriod-test-mode
boolean
default:false

Whether to operate against test-mode data. Defaults to false.

Body

application/json
​
name
string
required
Maximum string length: 100
​
address
string
required
Maximum string length: 64
​
country
string
required

Country ID (e.g. CL, MX, CO).

​
state
integer
required

State ID. Must belong to the chosen country.

​
currency
string

ISO currency code. Defaults from the country if omitted.

​
email
string<email> | null
​
phone
string | null
Maximum string length: 16
​
website
string<uri> | null
​
zip_code
string | null
Maximum string length: 16
​
manager
string | null
Maximum string length: 64
​
reference
string | null
Maximum string length: 64
​
tax_id
string | null
Maximum string length: 32
​
tax_settings
object
​
metadata
object
​
send_invoices
boolean
default:true
​
send_collections
boolean
default:true
​
send_vouchers
boolean
default:true

Response

Customer created.

​
name
string
required
Maximum string length: 100
​
address
string
required
Maximum string length: 64
​
country
object
required
​
state
object
required
​
id
string
read-only
Example:

"cus_01H8XYZ123ABC"

​
currency
string

ISO currency code (e.g. CLP, USD).

Example:

"CLP"

​
email
string<email> | null
​
phone
string | null
Maximum string length: 16
​
website
string<uri> | null
​
zip_code
string | null
Maximum string length: 16
​
manager
string | null

Account manager name (free text).

Maximum string length: 64
​
reference
string | null

External reference for the customer.

Maximum string length: 64
​
tax_id
string | null

Tax identifier. Required when the customer's country has tax regulation (e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's country.

Maximum string length: 32
​
tax_settings
object

Country-specific tax configuration. Schema and required keys depend on the tax agency of the customer's country.

​
metadata
object

Arbitrary key/value metadata. Filterable via ?metadata__key=value.

​
send_invoices
boolean
default:true

Whether to email invoices to the customer.

​
send_collections
boolean
default:true

Whether to email collection reminders to the customer.

​
send_vouchers
boolean
default:true

Whether to email payment receipts to the customer.

​
status
enum<string>
default:active
Available options:
active,
archived,
pending
​
contacts
object[]
read-only
​
sources
string[]
read-only

IDs of reusable payment sources currently chargeable or pending.

​
aggregations
object
​
test_mode
boolean
read-only
​
created
string<date-time>
read-only
​
updated
string<date-time>
read-only