Create a person (customer / supplier)
POST/people
Creates a person. Requires scope finance.people.write. workspace_id is always taken from the token. Set is_customer / is_supplier to make the row referenceable by receivables / payables. document_number (CPF 11 digits / CNPJ 14 digits) is validated and stored numeric-only; document_type is inferred from the length when omitted. Contact details (emails / phones), addresses, and bank/PIX coordinates are not yet writable via v1. Pass an X-Idempotency-Key header on retries.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 500
Person created. The Location header points at the new row.
Malformed JSON body.
Missing / invalid / expired / revoked token.
Token lacks the finance.people.write scope.
A person with the same document_number already exists for the company, or X-Idempotency-Key reuse with a different body.
Schema validation failure, invalid CPF/CNPJ check digits, or company_id not in the tenant.
Rate limit exceeded for this token. Reads and writes have separate budgets, both on a 1-hour sliding window. The response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After — wait out Retry-After rather than retrying immediately.
Unhandled server error.