Contacts

Contacts are the customers and suppliers in an organization. Each contact is a hub for their sales and purchase history. Use these endpoints to sync contacts from another system or look up the contactId you need when creating an invoice.

Both endpoints require the contacts:read scope; creating a contact also requires contacts:write. See Authentication.

Endpoints

Method	Path	Scope	Description
GET	/api/v1/contacts	contacts:read	List contacts (paginated or full).
POST	/api/v1/contacts	contacts:write	Create a contact.
GET	/api/v1/contacts/{id}	contacts:read	Fetch a single contact.

---

List contacts

Returns contacts for the token’s organization, sorted by name. You can either paginate explicitly or request the full list (capped at 500).

Request

curl https://app.accountfun.com/api/v1/contacts \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based). Sending page or limit (either one) switches on pagination and returns a pagination object.
limit	integer	25	Page size (max 200).
type	string	—	Filter by role: customer, supplier, or both.
search	string	—	Case-insensitive search across name, email, and phone.
includeInactive	string	false	Set to true to include deactivated contacts.

GET /api/v1/contacts?type=customer&search=northwind&page=1&limit=50

Pagination is opt-in

If you omit both page and limit, the endpoint returns up to 500 contacts in one response with no pagination object. Provide page and/or limit to get paginated results with a pagination envelope.

Response — 200 OK (paginated)

{
  "contacts": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "Northwind Traders",
      "email": "ap@northwind.example",
      "phone": "+1-555-0100",
      "contactType": "customer",
      "defaultCurrency": "USD",
      "isActive": true,
      "...": "..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 73,
    "totalPages": 2
  }
}

Response — 200 OK (unpaginated)

When page and limit are both omitted, the response contains only the contacts array (no pagination object):

{
  "contacts": [ { "...": "..." } ]
}

---

Create a contact

Creates a new contact (customer, supplier, or both). This requires contacts:write, and the authorizing user must hold a role with the manage_contacts permission.

Request

curl -X POST https://app.accountfun.com/api/v1/contacts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Supplies Ltd",
    "contactType": "supplier",
    "email": "sales@acme.example",
    "phone": "+1-555-0200",
    "defaultCurrency": "USD"
  }'

Body parameters

Field	Type	Required	Description
name	string	Yes	Contact name. Max 200 characters. Must be unique in the organization.
contactType	string	No	customer, supplier, or both. Defaults to customer.
email	string	No	Primary email. Must be a valid email address (or empty string).
phone	string	No	Phone number. Max 50 characters.
address	string	No	Postal address. Max 1000 characters.
firstName	string	No	Contact person first name. Max 100 characters.
lastName	string	No	Contact person last name. Max 100 characters.
primaryEmail	string	No	Alternative primary email for the contact person.
defaultCurrency	string	No	ISO 4217 code; must be an enabled org currency. Defaults to the org’s base currency.
settlementCurrency	string	No	Default settlement currency copied onto this customer’s new invoices. Must be an enabled org currency.
settlementRateSource	string	No	system (default) or manual.
remindersDisabled	boolean	No	If true, automatic invoice reminders are suppressed for this contact. Defaults to false.
defaultCc	string[]	No	Email addresses CC’d on every email sent to this contact.
defaultBcc	string[]	No	Email addresses BCC’d on every email sent to this contact.
website	string	No	Website URL. Max 500 characters.
linkedin	string	No	LinkedIn profile URL. Max 500 characters.
instagram	string	No	Instagram handle/URL. Max 500 characters.
facebook	string	No	Facebook profile/page URL. Max 500 characters.
twitter	string	No	Twitter/X handle/URL. Max 500 characters.

Response — 201 Created

{
  "contact": {
    "id": "00000000-0000-0000-0000-000000000002",
    "name": "Acme Supplies Ltd",
    "email": "sales@acme.example",
    "contactType": "supplier",
    "defaultCurrency": "USD",
    "isActive": true,
    "...": "..."
  }
}

Validation errors

Status	Cause
400	Invalid body (missing name, bad email, unknown currency).
403	Insufficient role (the user lacks the manage_contacts permission).
409	A contact with the same name already exists in this organization.

---

Fetch a single contact

Returns the full contact record.

Request

curl https://app.accountfun.com/api/v1/contacts/00000000-0000-0000-0000-000000000001 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response — 200 OK

{
  "contact": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Northwind Traders",
    "email": "ap@northwind.example",
    "phone": "+1-555-0100",
    "contactType": "customer",
    "defaultCurrency": "USD",
    "isActive": true,
    "remindersDisabled": false,
    "defaultCc": [],
    "defaultBcc": [],
    "...": "..."
  }
}

Response — 404 Not Found

Returned if no contact with that id exists in the token’s organization.

---

Contact types

A contact can be a customer (you invoice them), a supplier (you bill them), or both — useful for two-way trading relationships. The contactType field controls how the contact appears in filters and dropdowns throughout AccountFUN.

Value	Meaning
customer	Appears in customer pickers (invoices, quotes).
supplier	Appears in supplier pickers (bills, purchase orders).
both	Appears in both.