# Contacts > List, create, and fetch contacts (customers and suppliers) through the AccountFUN public API. Source: https://www.accountfun.com/docs/api/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](https://www.accountfun.com/docs/api/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 ```bash 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. | ```plaintext 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) ```json { "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): ```json { "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 ```bash 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](https://www.accountfun.com/docs/guides/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](https://www.accountfun.com/docs/guides/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` ```json { "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 ```bash curl https://app.accountfun.com/api/v1/contacts/00000000-0000-0000-0000-000000000001 \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Response — `200 OK` ```json { "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. |