insightlyjs is a lightweight Node.js library for the Insightly API v3.1.
The goal of InsightlyJS is to provide a simple and intuitive way to interact with the Insightly API.
The fetch API will be polyfilled if it is not available.
InsightlyJS will throw an error if you are using an unsupported runtime environment and is unable to polyfill.
npm install insightlyjs --save
import InsightlyJS from 'insightlyjs';
const InsightlyJS = require('insightlyjs').default;
Alternatively, you can use the async import()
function from CommonJS to load insightlyjs
:
const InsightlyJS = await import('insightlyjs');
Before you can use the module, you must configure it with your API key and API url.
You can locate them by logging into your Insightly account, and navigating to the following URL: https://crm.na1.insightly.com/Users/UserSettings/#apikey
Note: I am in the na1 region. Your region may be different. Adjust the URL accordingly.
const insightly = new InsightlyJS({
apiKey: '<your-api-key>',
apiUrl: 'https://<your-api-url>',
});
InsightlyJS is in development. Many of the methods are not yet implemented, but will be added soon. If you would like to help, please contact me.
getActivitySetList(options)
Retrieves a list of activity sets.
const activitySets = await insightly.getActivitySetList({
// Only return the top level properties of the activity sets.
brief?: boolean,
// Number of records to skip
skip?: number,
// Limit the number of records returned
top?: number,
// Reutrn the total amount of records
countTotal?: boolean
});
getActivitySet(id)
Retrieves an activity set by its ID.
const activitySet = await insightly.getActivitySet(12345);
getCommentFileAttachments(options)
Retrieves a list of comment file attachments.
const commentFileAttachments = await insightly.getCommentFileAttachments({
// Required - the ID of the comment
id: number,
// Required - ISO 8601 date string in the format YYYY-MM-DDTHH:MM:SSZ of the earliest date the file attachment was last updated
updatedAfterUtc?: string,
// Number of records to skip
skip?: number,
// Limit the number of records returned
top?: number,
// Reutrn the total amount of records
countTotal?: boolean
});
getContacts(options)
Retrieves a list of all contacts.
const contacts = await insightly.getContacts({
// Only return the top level properties of the contacts.
brief?: boolean,
// Number of records to skip
skip?: number,
// Limit the number of records returned
top?: number,
// Reutrn the total amount of records
countTotal?: boolean
});
getContact(id)
Retrieves a contact by its ID.
const contact = await insightly.getContact(12345);
getContactDates(id)
Retrieves a list of contact dates by the contact's ID.
const contactDates = await insightly.getContactDates(12345);
getContactEmails(id)
Retrieves a list of contact emails by the contact's ID.
const contactEmails = await insightly.getContactEmails({
// The ID of the contact
contactId: number,
// Earliest date the email was last updated
updatedAfterUtc?: string,
// Maximum number of records to return
top?: number,
// Number of records to skip
skip?: number,
// Reutrn the total amount of records
countTotal?: boolean,
// Return only the top level properties of the emails
brief?: boolean
});
getContactEvents(options)
Retrieves a list of contact events by the contact's ID.
const contactEvents = await insightly.getContactEvents({
// The ID of the contact
contactId: number,
// Earliest date the event was last updated
updatedAfterUtc?: string,
// Maximum number of records to return
top?: number,
// Number of records to skip
skip?: number,
// Reutrn the total amount of records
countTotal?: boolean,
// Return only the top level properties of the events
brief?: boolean
});
getContactFileAttachments(options)
Retrieves a list of contact file attachments by the contact's ID.
const contactFileAttachments = await insightly.getContactFileAttachments({
// The ID of the contact
contactId: number,
// Earliest date the file attachment was last updated
updatedAfterUtc?: string,
// Maximum number of records to return
top?: number,
// Number of records to skip
skip?: number,
// Reutrn the total amount of records
countTotal?: boolean,
});
getContactFollowState(id)
Retrieves the follow state of a contact by its ID.
const contactFollowState = await insightly.getContactFollowState(12345);
getContactLinks(id)
Retrieves a list of contact links by the contact's ID.
const contactLinks = await insightly.getContactLinks(12345);
getContactNotes(options)
Retrieves a list of contact notes by the contact's ID.
const contactNotes = await insightly.getContactNotes({
// The ID of the contact
contactId: number,
// Earliest date the note was last updated
updatedAfterUtc?: string,
// Maximum number of records to return
top?: number,
// Number of records to skip
skip?: number,
// Reutrn the total amount of records
countTotal?: boolean,
// Return only the top level properties of the notes
brief?: boolean
});
getContactTags(id)
Retrieves a list of contact tags by the contact's ID.
const contactTags = await insightly.getContactTags(12345);
getContactTasks(options)
Retrieves a list of contact tasks by the contact's ID.
const contactTasks = await insightly.getContactTasks({
// The ID of the contact
contactId: number,
// Earliest date the task was last updated
updatedAfterUtc?: string,
// Maximum number of records to return
top?: number,
// Number of records to skip
skip?: number,
// Reutrn the total amount of records
countTotal?: boolean,
// Return only the top level properties of the tasks
brief?: boolean
});
searchContacts(options)
Retrieves a list of contacts that match the search criteria.
const searchResults = await insightly.searchContacts({
query: {
first_name: string
},
top?: number,
skip?: number,
countTotal?: boolean
brief?: boolean
});
searchContactsByTag(options)
Retrieves a list of contacts that match the tag provided.
const searchResults = await insightly.searchContactsByTag({
tagName: string,
top?: number,
skip?: number,
countTotal?: boolean
brief?: boolean
});
I am looking for someone to help build examples while I focus on the core functionalities of the library. Please contact me if you would like to help.
Types are bundled with the library, so you don't need to insstall any additional packages.
To use the types, import them into your project like so:
import { Contact } from "insightlyjs";
While it is possible to use the Insightly API to perform CRUD actions, some actions are unavailable, such as assigning a contact to an Activity. This appears to be a limitation on Insightly's end.
For a complete list of limitations and a more in-depth explanation, see this issue.
You can email me with any question, suggestions, or concerns.