Contacts API — Create, Retrieve, and Update Contacts

Contacts represent individual people inside a company. Each contact must be linked to a company via companyId. You can attach a role, mark one contact as primary, and store arbitrary key-value data in customFields.

All contacts endpoints are scoped to your tenant. Pass your API key in the Authorization: Bearer header on every request.

List contacts

GET /api/v1/contacts/contact Returns a paginated list of contacts for the authenticated tenant. Filter by company or run a full-text search across names and emails.

Query parameters

string

Filter contacts belonging to a specific company. Must be a valid UUID.

string

Full-text search across contact names and email addresses.

integer

default:"1"

1-based page index.

integer

default:"25"

Number of results per page. Maximum 100.

Response

{
  "data": [
    {
      "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "companyId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@acme.com",
      "phone": "+15550001234",
      "role": "Procurement Manager",
      "isPrimary": true,
      "notes": null,
      "customFields": {},
      "createdAt": "2024-03-15T10:30:00Z",
      "updatedAt": "2024-03-15T10:30:00Z"
    }
  ],
  "total": 84,
  "page": 1,
  "pageSize": 25
}

curl -X GET "https://app.novala.ai/api/v1/contacts/contact?companyId=d290f1ee-6c54-4b01-90e6-d701748f0851" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/v1/contacts/contact?companyId=d290f1ee-6c54-4b01-90e6-d701748f0851',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data, total } = await response.json();

Create a contact

POST /api/v1/contacts/contact Creates a new contact linked to an existing company.

Request body

string

required

UUID of the company this contact belongs to.

string

required

Contact’s first name. Maximum 100 characters.

string

required

Contact’s last name. Maximum 100 characters.

string

Contact’s email address. Must be a valid email format.

string

Contact’s phone number. Maximum 50 characters.

string

Job title or role within the company. Maximum 100 characters.

boolean

When true, marks this as the primary contact for the company.

string

Internal notes about this contact.

object

Key-value map of custom field data. Any required custom fields your tenant has configured must be included.

Response

Returns 201 Created with the new contact wrapped in { "data": {...} }.

curl -X POST https://app.novala.ai/api/v1/contacts/contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@acme.com",
    "role": "Procurement Manager",
    "isPrimary": true
  }'

const response = await fetch('https://app.novala.ai/api/v1/contacts/contact', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    companyId: 'd290f1ee-6c54-4b01-90e6-d701748f0851',
    firstName: 'Jane',
    lastName: 'Doe',
    email: 'jane.doe@acme.com',
    role: 'Procurement Manager',
    isPrimary: true,
  }),
});
const { data } = await response.json(); // 201 Created

Get a contact

GET /api/v1/contacts/contact/{id} Retrieves a single contact by ID.

Path parameters

string

required

UUID of the contact.

Response

Returns 200 OK with { "data": { contact object } }. Returns 404 Not Found if the contact does not exist or belongs to a different tenant.

Response fields

object

Show Contact object

string

UUID of the contact.

string

UUID of the associated company.

string

First name.

string

Last name.

string | null

Email address.

string | null

Phone number.

string | null

Role or job title at the company.

boolean

Whether this is the primary contact for the company.

string | null

Internal notes.

object

Custom field key-value pairs.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

curl -X GET https://app.novala.ai/api/v1/contacts/contact/3f2504e0-4f89-11d3-9a0c-0305e82c3301 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/v1/contacts/contact/3f2504e0-4f89-11d3-9a0c-0305e82c3301',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data } = await response.json();

Update a contact

PATCH /api/v1/contacts/contact/{id} Partially updates a contact. Only include the fields you want to change. Pass null to clear a nullable field.

Path parameters

string

required

UUID of the contact to update.

Request body

All fields are optional.

string

Updated first name. Maximum 100 characters.

string

Updated last name. Maximum 100 characters.

string | null

Updated email address. Pass null to clear.

string | null

Updated phone number. Pass null to clear.

string | null

Updated role. Pass null to clear.

boolean

Whether to mark this contact as the primary contact.

string | null

Updated internal notes. Pass null to clear.

object

Replaces all custom field values with the provided map.

Response

Returns 200 OK with { "data": { updated contact } }. Returns 404 Not Found if the contact does not exist.

curl -X PATCH https://app.novala.ai/api/v1/contacts/contact/3f2504e0-4f89-11d3-9a0c-0305e82c3301 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "VP of Operations", "isPrimary": true }'

const response = await fetch(
  'https://app.novala.ai/api/v1/contacts/contact/3f2504e0-4f89-11d3-9a0c-0305e82c3301',
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ role: 'VP of Operations', isPrimary: true }),
  }
);
const { data } = await response.json();

Overview

Endpoints

Contacts API — Create, Retrieve, and Update Contacts

List contacts

Query parameters

Response

Create a contact

Request body

Response

Get a contact

Path parameters

Response

Response fields

Update a contact

Path parameters

Request body

Response

​List contacts

​Query parameters

​Response

​Create a contact

​Request body

​Response

​Get a contact

​Path parameters

​Response

​Response fields

​Update a contact

​Path parameters

​Request body

​Response

List contacts

Query parameters

Response

Create a contact

Request body

Response

Get a contact

Path parameters

Response

Response fields

Update a contact

Path parameters

Request body

Response