Get, update, or archive a contact
API Documentation / Resources / Contacts

Get a contact
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id}
Required OAuth scope: contacts:read
Returns one contact with available address and contact-person details. Contacts outside the granted subsidiary context are not disclosed.
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. |
contact_id |
path | Yes | string (uuid) | UUID of a customer or supplier contact. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Contact details. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
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": [
{
"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"
}
}
Update a contact
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id}
Required OAuth scope: contacts:write
Updates any supplied mutable contact fields; omitted fields remain unchanged.
When addresses or contact_people is supplied, the collection is the
desired public representation for that nested data. Integrations should
send the complete collection they intend to retain rather than relying on
undocumented positional merging.
A contact must remain a customer, supplier, or both.
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. |
contact_id |
path | Yes | string (uuid) | UUID of a customer or supplier contact. |
Request
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"invoice_email": "billing@koru.example",
"currency_code": "NZD"
}
Required body fields: None.
Responses
| Status | Description |
|---|---|
200 |
Updated contact. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with inheritance, open invoices, or uniqueness. |
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": [
{
"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"
}
}
Archive a contact
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id}
Required OAuth scope: contacts:write
Archives a contact and removes it from future selection.
| Contact state | Result |
|---|---|
| No draft or unpaid invoices | 204 No Content |
| Draft invoice exists | 409 contact_has_open_invoices |
| Unpaid authorised invoice exists | 409 contact_has_open_invoices |
| Directory inherited from parent | 409 contacts_inherited |
Closed invoices and accounting history remain attached to the archived contact. Use the restore operation to make it selectable again.
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. |
contact_id |
path | Yes | string (uuid) | UUID of a customer or supplier contact. |
Request
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/contacts/{contact_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
204 |
Contact archived. The response has no body. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with inheritance, open invoices, or uniqueness. |