List or create contacts
API Documentation / Resources / Contacts

List contacts
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts
Required OAuth scope: contacts:read
Lists customer and supplier counterparties visible to the subsidiary.
| Filter | Meaning |
|---|---|
type |
customer, supplier, or both |
active |
Active or archived contacts |
updated_since |
Changed at or after an RFC 3339 timestamp |
search |
Name, tax identity, invoice email, or phone |
Sort by name, created_at, or updated_at; the default is name ASC
followed by stable resource order.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
type |
query | No | string: customer, supplier, both | |
active |
query | No | boolean | |
updated_since |
query | No | string (date-time) | |
search |
query | No | string | |
page |
query | No | integer | |
per_page |
query | No | integer | |
sort |
query | No | string: name, created_at, updated_at | |
order |
query | No | string: asc, desc |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of contacts. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
422 |
One or more supplied values failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
"name": "Koru Office Limited",
"type": "customer",
"tax_identity": "NZ123456789",
"invoice_email": "[email protected]",
"currency_code": "NZD",
"payment_term_id": null,
"addresses": [],
"contact_people": [],
"active": true,
"created_at": "2026-08-10T12:30:00Z",
"updated_at": "2026-08-10T12:30:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 30,
"last_page": 1,
"total": 1
}
}
Create a contact
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts
Required OAuth scope: contacts:write
Creates a customer, supplier, or dual-purpose counterparty.
Nested data
| Field | Behavior |
|---|---|
addresses |
Creates the supplied postal addresses with the contact. |
contact_people |
Creates named people; at most one should be primary. |
payment_term_id |
Must identify an active term in the subsidiary. |
currency_code |
Must be enabled for the subsidiary. |
A subsidiary that inherits its contact directory must create and maintain
contacts at the source subsidiary and returns 409 contacts_inherited.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
Request
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "Koru Office Limited",
"type": "customer",
"tax_identity": "NZ123456789",
"invoice_email": "accounts@koru.example",
"currency_code": "NZD",
"contact_people": [
{
"name": "Mia Chen",
"email": "mia@koru.example",
"phone": "+64 9 555 0182",
"primary": true
}
]
}
Required body fields: name, type.
Responses
| Status | Description |
|---|---|
201 |
Contact created. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
409 |
Request conflicts with inheritance, open invoices, or uniqueness. |
422 |
One or more supplied values failed validation. |
201 example
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
"name": "Koru Office Limited",
"type": "customer",
"tax_identity": "NZ123456789",
"invoice_email": "[email protected]",
"currency_code": "NZD",
"payment_term_id": null,
"addresses": [],
"contact_people": [
{
"name": "Mia Chen",
"email": "[email protected]",
"phone": "+64 9 555 0182",
"primary": true
}
],
"active": true,
"created_at": "2026-08-10T12:30:00Z",
"updated_at": "2026-08-10T12:30:00Z"
}
}