finov.ioDocumentationHome

Get, update, or archive a contact

API Documentation / Resources / Contacts

Finovio entity detail page showing the Itechs supplier summary and accounting activity
Entity records combine company details with linked invoices and journals.

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.