finov.ioDocumentationHome

List or create contacts

API Documentation / Resources / Contacts

Finovio Create entity page with entity details and main contact sections
Record the company type, billing defaults, and main contact in one form.

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"
  }
}