Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
companyId
string
Filter contacts belonging to a specific company. Must be a valid UUID.
​
search
string
Full-text search across contact names and email addresses.
​
page
integer
default:"1"
1-based page index.
​
limit
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"

​
Create a contact

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

​
Request body

​
companyId
string
required
UUID of the company this contact belongs to.
​
firstName
string
required
Contact’s first name. Maximum 100 characters.
​
lastName
string
required
Contact’s last name. Maximum 100 characters.
​
email
string
Contact’s email address. Must be a valid email format.
​
phone
string
Contact’s phone number. Maximum 50 characters.
​
role
string
Job title or role within the company. Maximum 100 characters.
​
isPrimary
boolean
When true, marks this as the primary contact for the company.
​
notes
string
Internal notes about this contact.
​
customFields
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
  }'

​
Get a contact

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

​
Path parameters

​
id
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

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

​
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

​
id
string
required
UUID of the contact to update.

​
Request body

All fields are optional.
​
firstName
string
Updated first name. Maximum 100 characters.
​
lastName
string
Updated last name. Maximum 100 characters.
​
email
string | null
Updated email address. Pass null to clear.
​
phone
string | null
Updated phone number. Pass null to clear.
​
role
string | null
Updated role. Pass null to clear.
​
isPrimary
boolean
Whether to mark this contact as the primary contact.
​
notes
string | null
Updated internal notes. Pass null to clear.
​
customFields
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 }'