Insightly
The Insightly connector reads and writes contacts, organisations, opportunities, leads and tasks through Insightly's REST v3.1 API.
When to use it
- You move contacts, organisations and opportunities between Insightly and another CRM.
- You push new customers from a database into Insightly as contacts, or pull won opportunities into a warehouse.
- You read records, transform them, and write the results back with Update.
What you need
- Your Insightly pod.
- An Insightly API key.
Insightly offers an API key only.
Find your pod
Sign in to Insightly and look at the browser address bar. The label after
https:// is your pod, such as na1 or eu1. Enter the label alone. A value
with a dot, a slash, a colon or an at sign is refused.
The key belongs to a user
Insightly issues one API key per user, and a connection sees what that user sees. A key from a restricted user reads fewer records than a key from an administrator.
Set up in Insightly
- Sign in to Insightly and note the pod label in the address bar.
- Go to User Settings > API Key and copy the key.
- In DataLug, add an Insightly connection.
- Enter the pod and paste the API key.
- Click Test connection.
Connect
The connection form lists its steps on the left. Open any step from that list. The Environments step holds the values that differ per environment.
Test connection is in the form footer. Beside it, Test against picks Base, the connection as saved, or an environment, whose values are applied first.
| Field | Step | What to enter |
|---|---|---|
| Auth Type | Authentication | API Key. Insightly offers an API key only. |
| API Key | Authentication | From User Settings > API Key. One key per user. |
| Pod | Connection | The label in your Insightly address, such as na1. |
Stored secrets are never sent back to the browser. To change one, use Replace.
Supported operations
Objects. Contact, Organisation, Opportunity, Lead and Task. The API name is
Organisations.
| Action | Node | Operations |
|---|---|---|
| Query (Source) | Source node | Query, with an optional Limit |
| Load (Target) | Load node | Insert, Update, Delete |
Writes go one record per request, matched on the record id, such as
CONTACT_ID or ORGANISATION_ID.
Not supported: Upsert, a source filter, Notes.
How the field list is built
Insightly's custom fields endpoint lists only the fields you added. DataLug reads one record of the object and takes the standard fields from its keys, then adds your custom field definitions.
- A standard field's type comes from one value. Numbers, true or false and ISO dates are recognised. Anything else is text, including a field that was empty on the sampled record. The value still transfers.
- An object with no records has no standard fields. Custom fields still appear. Create one record in Insightly and click Get Fields.
Custom field names and types come from Insightly directly.
Limits
Insightly allows 10 requests per second, and a daily request allowance that
depends on the plan: 1,000 on the free plan and up to 100,000 on Enterprise.
Insightly answers 429 past either limit. See Insightly's
API documentation.
DataLug paces Insightly connections at 10 requests per second by default. DataLug does not track the daily allowance. Page size is at most 500.
The API limits card on the connection form is collapsed by default. Every field on it is optional, and a blank field uses the default shown below it.
| Setting | What it does | Default |
|---|---|---|
| Requests per period, Period | Paces outgoing calls. Set both to throttle. | No throttle, or the rate shown on the card. |
| Page size | Rows per request. A larger value is reduced to the provider's maximum. | The maximum shown on the card, or set by the provider. |
| Max attempts | Tries per call, including the first. | 3 |
| Cool-off (ms) | The first wait after a 429. Later waits grow from it. | 500 ms |
| Requests at once | Requests open at the same time within one run. | No limit |
A Retry-After header from the provider overrides the cool-off. The pace
applies per connection and is shared by every run on it. See
Run performance.
DataLug retries a call that the provider refused with 429, and a call that
could not connect. A read is also retried after a 408, a 5xx or a dropped
connection. A write is retried only after a 429 or a failed connection.
A Retry-After delay of up to one minute is honoured. A longer one fails the
call with the 429.
Troubleshooting
| What you see | What it means | What to try |
|---|---|---|
Add the pod to this Insightly connection and save before testing. | Pod is blank or not a plain label. | Enter the label alone, such as na1. |
401 on test or on a run | The key is wrong, or its user was deactivated. | Copy the key from User Settings > API Key and paste it with Replace. |
| An object reads fewer records than you see in Insightly | The key belongs to a restricted user. | Use a key from a user who can see the records the data pipeline needs. |
| A field is missing from the picker | The object has no records to read standard fields from. | Create one record in Insightly and click Get Fields. |
| A number field is offered as text | It was empty on the sampled record. | Map it. The value still transfers. |
429 Too Many Requests | Past 10 requests a second, or out of daily allowance. | The run backs off and retries. If it recurs the same day, check your plan's daily allowance. |
Related
- Source node and Load node.
- Connections for environments and sharing.
- HubSpot and Copper.