Version 2.2 of the Insightly API live and available

We are pleased to announce that version 2.2 of the Insightly web API is officially live, and can be accessed at api.insight.ly/v2.2/Help. Read more on Working with the Insighty Web API.

The new API includes significant improvements in performance, ease of use and documentation, so we encourage customers to check it out. Among the improvements:

Improved performance, especially when accessing large recordsets, including support for pagination

We now support incremental changes to existing objects. For example, you can easily add an address to a contact by posting to /contacts/{id}/addresses. This enables you to make changes to an existing object without having to upload the entire object graph.

OData is replaced with a simpler set of optional query parameters. For example, to search contacts by email, just GET /contacts/search?email=foo@bar.com

Support for new custom field types.

And more, go the API site for full details and documentation. We will also be updating client side libraries to support v2.2 in the near future (the Python SDK will be updated first with more to follow).

Thanks for using Insightly.

Brian McConnell

Insightly Engineering Team

6

Comments

34 comments
  • Hello Brian,

     

    Thanks for the update! I have an issue while testing it with XML, for an integration I have implemented with v2.1. Even though I have set both Content-type and Accept headers to 'text/xml', it still returns the results in JSON format. Is this a known issue for you or am I doing something wrong? Any help would be highly appreciated!

    Thank you in advance!

     

    0
    Comment actions Permalink
  • Hi Lindjana,

    We're deprecating XML support in v2.2. If you are using a programming language that we have client libraries for it should be pretty easy to move to JSON. v2.2 of our API also supports Swagger which allows you to auto-generate api wrappers for you're desired language, supports up to 15 different languages. We're still fine tuning our Swagger Spec but most of the functionality is there already. 

    Insightly Swagger Spec:

    https://api.insight.ly/v2.2/swagger/docs/v2.2

    CodeGen:

    https://github.com/swagger-api/swagger-codegen

     

    0
    Comment actions Permalink
  • Hi,

    I've had a go at using version 2.2 and the best thing about it so far is that it appears much quicker.  Is that just because less people are using it?

    One 'bug' that I've found concerns the 'Date_Updated_Utc' field on Contacts and Organisations.  When I do a search using the new 'updated_after_utc' filter: i.e.

    /v2.2/organisations/search?updated_after_utc=2015-11-16T09:02:14

    I find that some of the organisations returned have a Date_Updated_Utc before that specified in the filter.

    From a bit of trial an error, it appears that when adding a tag to an organisation (or contact) it updates some internal/private datetime field, but not the Date_Updated_Utc field.  I assume that the updated_after_utc filter uses this internal datetime hence the wrong data is returned.

    Because of this bug I've had to revert to using v2.1:

    /v2.1/organisations?$filter=DATE_UPDATED_UTC%20gt%20DateTime'2015-11-16T09:02:14'

    which returns the correct data set.

    Are you aware of this bug, and if so do you have any timescales on fixing?

    Thanks.

     

    0
    Comment actions Permalink
  • Hi Gareth,

    Thanks for your feedback! The updated_after_utc filter looks at all the data in the object graph and if there's been an update returns the full graph. As you've discovered it looks at Tags, Links, Organisation Links etc.

    Based on you description it sounds like you only want to know if the top level properties, custom fields, addresses, contact infos, or dates for the Organisation has been updated. In this case you'll need to do some additional filtering on the client using DATE_UPDATED_UTC on the Organisation.

    0
    Comment actions Permalink
  • Hi Patrick,

    Thanks for that information, a couple questions:

    Is it still possible to filter by DATE_UPDATED_UTC on the Organisation using v2.2, and if so how?

    In the data that is returned from the API, is it possible to access the last updated date in the object graph?   What I mean is, if a tag has been added to an organisation and a date updated somewhere, where is that date stored and is it returned in the JSON from the API?

    Finally, if a tag (custom field, link etc) has been added to an Organisation, why is it's DATE_UPDATED_UTC not updated?

    Thanks for your help,

    Gareth

    0
    Comment actions Permalink
  • Hi Gareth,

    Unfortunately it's not possible, you'll have to do some additional filtering on the client using DATE_UPDATED_UTC. Tags have their internal date not exposed through the API, that's basically why. 

     

    0
    Comment actions Permalink
  • Hi,

     

    I have begun using the api V2.2 using the python sdk and have ran into a bit of issue. I can't seem to update the OPPRTUNITY_VALUE field for existing opportunities (I did not test uploading new opportunities yet). I also opened an issue on github (https://github.com/Insightly/insightly-python/issues/30).

    Another thing that I could not find how to do using the python sdk is updating opportunities in batch. The only way I got the update method to work was by iterating over all records and updating them one by one. This is obviously suboptimal in terms of performance and I was wondering whether I am perhaps missing something trivial about how to do this.

    Thanks,

    oded

    0
    Comment actions Permalink
  • Hi guys - does this add any extra functionality to PowerBI?

    0
    Comment actions Permalink
  • Hello Oded,

    OPPORTUNITY_VALUE is a read-only, calculated field based on BID_AMOUNT, BID_TYPE and BID_DURATION. Please use these three fields to update it.

    Regarding bulk updates, we currently do not support that through our API. It may be something we'll implement in the future but it's not on our road map at the moment. A good way to increase the likelihood of this being implemented is to create a feature suggestion for it where other users can vote on it as well.

    0
    Comment actions Permalink
  • Hello Kyle,

    This will not add any extra functionality to PowerBI. Let us know if you have something in particular that you are looking for.

    0
    Comment actions Permalink
  • Hi I got Insigthly SDK by Brian McConnell,  who I would like to say thanks for share your knowledge about python /Insightly API very usefully!

     I am an Insightly user and starting to create python codes… very  beginner programmer, but my first task is create an internal app integrated with Insightly, where a need to get an opportunity ID, and the organization code/name that they are into  opportunities/LINKS….  I can´t do  that! D

    how I can do that, somebody can help me !

     

    tks in advance

    Carmello

    0
    Comment actions Permalink
  • Hey carmello:

    There is a reply to this in your other post here :)

    0
    Comment actions Permalink
  • I've recently started to hit v2.2, and I'm confused about adding notes -- I used the same call I had been using for 2.1 to add notes and the response was that the verb wasn't supported, so I went to check the docs and it seems like there's no way to add notes anymore? Just retrieve, update, and delete them? Is this a bug or what?  

    0
    Comment actions Permalink
  • Hi Pete,

    We're sorry for the inconvenience but we ended up moving the Notes POST endpoint in v2.2 for consistency reasons because, like a Comment, a Note always requires a Subject to which it will be linked. Adding a Note to a Contact in v2.2 can now be done via a POST to /contacts/{id}/notes. Another benefit is that you no longer have to submit LINK_SUBJECT_ID and LINK_SUBJECT_TYPE in the POST as we map them automatically from route. You also have the convenience of retrieving Notes for a particular Contact via GET /contacts/{id}/notes. Same patterns apply for all the other objects that support Notes, like Organisations, Opportunities, Projects and Leads

    Best Regards,

    Patrick

    0
    Comment actions Permalink
  • Seems like a good change to the API, but unfortunately means more invasive changes to the ruby-insightly gem are necessary than just changing the url and adding the word "Search" to some endpoints. When is the official updated gem going to be released, or am I SOL for the foreseeable future? 

    0
    Comment actions Permalink
  • Hi Pete,

    Unfortunately, we do not officially provide in house support for Ruby. It has largely been an effort by our customers and community to keep it up to date. We implemented Swagger/OpenAPI Specification to provide the option to generate client libraries in currently 15+ different programming languages. We're planning to add more documentation about it but in the meantime you can find information on how to use the Code Generation Tool here

    Best Regards,

    Patrick

    0
    Comment actions Permalink
  • I see--that's bad news. I assumed that the insightly-ruby gem was official since it was on the official github account (https://github.com/Insightly/insightly-ruby ), and I've been fighting with the API ever since trying to get it integrated. I only signed up for Insightly because of the API and the ruby support. I think it makes sense to cut my losses and back out of the integration now.

    For what it's worth, codegen sucks. It seems like an awesome idea because the API is the API and if people can automatically generate their own client library around it that then they get an API wrapper, you don't have to maintain anything, and everyone is happy. Except it doesn't really work in practice because languages have conventions and cultures around them that codegen doesn't really know about, so the interface is bound to awkwardly land in an uncanny valley of sort of working, but feeling confusing and bad the whole time. (What might work better is using codegen internally, then taking the product and having an expert in the given language make it actually work).

    Another part that is bad, especially in concert with the codegen, is that the data structures you send back are bad, and I can see one reason why too--you're using the default .NET serialization so you need to do crazy things like return a tags array that's actually an array of objects, each of which have a member called "tag_name." You should never have exposed a structure like that, and given that you did the ruby library should have mapped it to a sane array. But neither of those things are true. Custom fields are uselessly named CUSTOM_FIELD_N with no indication of what I might know them as. 

    Anyway, I'm giving up now before I come to regret hitching my wagon to this API. Sorry man, I believe that you and the team are trying hard, but it's not working for me.

    0
    Comment actions Permalink
  • Hi Pete, 

    Ruby insightly gem started out as a open community project to help our customers. Though we are not officially supporting it, we have been constantly working with the community and making updates/fixes based on customer needs. We will be updating our ruby insightly gem to the latest changes in our API. (V22). These changes should come in the short term future. 

    1
    Comment actions Permalink
  • Hi, I found a bug where Contacts/Search?tag=TAGNAME  will search for contacts with tags that begin with that "TAGNAME", not just exact matches, which is not the expected behavior.

    0
    Comment actions Permalink
  • Hello Vladimir,

    Thanks for pointing it out!

    I've logged an internal ticket and will follow up on this thread when the fix is ready. Sorry for the inconvenience!

     

    1
    Comment actions Permalink
  • Hello Vladimir,

    We have published a fix that would perform an exact match while searching for contacts with tags using v2.2. Check it out and please let us know if you have further questions.

     

    Thanks!

    0
    Comment actions Permalink
  • Hi,

    I'm a bit new to API testing (with POSTMAN), and am having trouble trying POST requests.

    The v2.2 API docs do not list required parameters for Add (POST) like was done for the v2.1 API docs; for example, https://api.insight.ly/v2.2/Help#!/Events/AddEvent

    The v2.2 API docs imply that a complete object is now required(?)

    ... but the v2.2 API docs about PUT (update) state

    "One of the biggest changes we've made is to enable updates to Insightly entities without the need to provide the entity's full object graph."

    ... although that conflicts with https://support.insight.ly/hc/en-us/articles/204061444 (probably just needs updating?)

    "When you update an object, you need to PUT (update) the entire object graph, including all sub-elements attached to the parent object (such as addresses and other contact points). ..."

     

    What do I need to provide as the POST body to add a new Insightly object (Event, say)?

     

    Regards,

    Ian

     

    0
    Comment actions Permalink
  • Hello Ian,

    You will be able to find the list of required and optional parameters for a POST call under the Body Schema section on the right side. If it is not visible to you, click on the "Show samples" link to expand the right side.

     

    Hope this helps!

    0
    Comment actions Permalink
  • Is v2.2 API really live, or still in Beta?

    I'm trying to encourage our developers to use v2.2 but they are sticking to v2.1 because the Insightly help still says that the v2.2 API is in Beta

    eg on https://api.insight.ly/v2.2/Help#!/Overview/Introduction

    0
    Comment actions Permalink
  • Hello Ian,

    API v2.2 is live. Even though it says it's in beta, it is fairly stable. It offers significant improvements over v2.1 and I'd highly recommend using it.

    0
    Comment actions Permalink
  • I'm really looking forward to an updated Asp.Net SDK, especially examples showing filtering/searching and pagination.

    I'm currently trying this, which is not working:

    var filters = new List<string>();
    filters.Add("ORGANISATION_NAME='" + model.SearchTerm + "'");

    string api_key = ConfigurationManager.AppSettings.Get("InsightlyApiKey");
    Insightly i = new Insightly(api_key);
    var orgs = i.GetOrganizations(filters: filters);

    I am getting unfiltered results back.  I really need to get Search working.

    0
    Comment actions Permalink
  • Hello Laura,

    ODATA filter for searching by organisation name would be: ORGANISATION_NAME eq 'HNTB Corporation'.

    Please refer to our Technical Details page for more ODATA examples.

    0
    Comment actions Permalink
  • Hi Guys,

    It appears that search by phone number is not working for Contacts, Leads or Organizations (I posted the same here: https://support.insight.ly/hc/en-us/community/posts/115006942188/comments/115003039708)

    Here is an example:

    https://pptyb7qv.insight.ly/Contacts/Details/207596499 has the phone number 4802365477

    searching with 

    https://api.insight.ly/v2.2/Contacts/Search?phone_number=4802365477&brief=false&count_total=false

    returns an empty set of data.

    Thanks,

    -Keith

    0
    Comment actions Permalink
  • Hello Keith,

    We are working on fixing this bug. Thanks for pointing it out!

    0
    Comment actions Permalink
  • Hello.  I have a question about adding responsible user id and owner user id when creating a lead.  

    With responsible user id, I get an error saying I need to ensure that my value is an integer and a valid user id.  I have confirmed that I am using an integer and that it is a valid user id.

    With owner user id, I get no error but the owner does not get assigned.

    Are these two fields available for setting using a POST request or might there be an issue with those fields? 

     

    Thanks for your time.  Sincerely,

     

    Stuart Sequeira

    0
    Comment actions Permalink

Please sign in to leave a comment.