iinsight | Developer portal
www.iinsight.biz

API version 1 Contacts

1. List Company Contacts (api1/company_contacts)

This method will answer with a collection of iinsight's contacts (contact oriented data) that has been modified/created since a provided date. The collection will be in JSON format.
The results would be paginated, having a maximum of 100 records per page. An empty collection and a status code 200 response, means that there is no records in the specified page.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/company_contacts GET
PRODUCTION https://api-usa.iinsightonline.com/api1/company_contacts GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
modified_since Date since last update or insert. Format yyyy-mm-dd (i.e.: 2022-12-31)
Use "1900-01-01" to get all contacts no matter the modified or created date.		 Yes
page The page number of the paginated results. (i.e.: 1) Yes
Response
[  
      {
        "contact_id": "556", // internal iinsight ID
        "first_name": "xxx",
        "last_name": "xxx",
        "job_title":"",
        "company_id": "99",
        "company_name": "Company Name",
        "email": "xxxyyy@compmany.com",
        "position": "",
        "department": "Case Manager",
        "street": "101 Phillip Street",
        "postcode": "2000",
        "suburb": "Sydney",
        "state": "New South Wales",
        "country": "Australia",
        "phone1": "123456789",
        "phone2": "",
        "fax": "",
        "mobile": "",
        "notes": "",
        "provider_no": "123456789",
        "biller_id": "Plan Managed",
        "disabled": "No"  // Yes / No
    }
]

2. List Case Contacts (api1/case_contacts)

This method will answer with a collection of iinsight's contacts (contact oriented data) that has been modified/created since a provided date. The collection will be in JSON format.
The results would be paginated, having a maximum of 100 records per page. An empty collection and a status code 200 response, means that there is no records in the specified page.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/case_contacts GET
PRODUCTION https://api-usa.iinsightonline.com/api1/case_contacts GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
modified_since Date since last update or insert. Format yyyy-mm-dd (i.e.: 2022-12-31)
Use "1900-01-01" to get all contacts no matter the modified or created date.		 Yes
page The page number of the paginated results. (i.e.: 1) Yes
Response
[
    {
        "contact_id": "553", // internal iinsight ID
        "case": "NAT111",
        "company_name": "xxx",
        "title": "xx",
        "first_name": "xxx",
        "last_name": "xxx",
        "position": "Account Manager",
        "department": "Accounts",
        "street": "226 Burraneer Bay Road",
        "postcode": "2229",
        "suburb": "Caringbah South",
        "sublocality": "Sutherland Shire Council",
        "state": "New South Wales",
        "country": "Australia",
        "email": "xxx",
        "phone1": "55555",
        "phone2": "66666",
        "fax": "77777",
        "mobile": "88888",
        "provider_no": "xxx",
        "biller_id": "123456",
        "job_title": "",
        "notes": "",
        "disabled": "No",
        "contact_role_bill_to": "Yes",
        "contact_role_employer": "No",
        "contact_role_referrer": "Yes",
        "contact_role_bill_to_cc": "No"
    },
    {
        "contact_id": "554",
        "case": "NAT111",
        "company_name": "xxx",
        "title": "",
        "first_name": "xxx",
        "last_name": "xxx",
        "position": "",
        "department": "",
        "street": null,
        "postcode": null,
        "suburb": null,
        "sublocality": null,
        "state": null,
        "country": null,
        "email": "",
        "phone1": "5555",
        "phone2": "",
        "fax": "",
        "mobile": "",
        "provider_no": "",
        "biller_id": "123456",
        "job_title": "",
        "notes": "",
        "disabled": "No",
        "contact_role_bill_to": "No",
        "contact_role_employer": "Yes",
        "contact_role_referrer": "No",
        "contact_role_bill_to_cc": "Yes"
    }
]

3. List Contacts (api1/contacts)

This method will answer with a collection of iinsight's contacts (contact oriented data) that belong to a case. The collection will be in JSON format.
The results can be paginated, giving a limit per page not greater than 100 and it be filter by contact status, search criteria or sorted by asc or desc. An empty collection and a status code 200 response, means that there is no records in the specified page and filters.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts GET
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
case_id Case ID. (i.e.: 1) No
company_id Company ID. (i.e.: 1) No
fields Contacs fields seperated by comma and no blank spaces. (i.e.: field_name1,field_name2,...) Yes
status Filter by contact status. Options: all, active and disabled No
sort_col Sort by column field name. (i.e.: field_name) No
sort_type Sort column type. Options: asc, desc No
search_criteria Search field name. (i.e.: {"field_name1":"value1","field_name2":"value1,value2"}) No
page The page number of the paginated results. (i.e.: 1) No
limit The limit amount of items. (i.e.: 1) No
Response
[
      {
        "contact_id": "4", // internal iinsight ID
        "company_name": "xxxxx",
        "job_title": "xxx",
        "position": "Account Manager",
        "phone1": "(##) #### ####",
        "mobile": "",
        "email": "xxxx@xxx.xx",
        "address": "xxx xxxxx xxxxx",
        "suburb": "xxxx",
        "state": "xxxx",
        "postcode": "xxxx",
        "date_created": "##-##-####",
        "date_disabled": "##-##-####",
        "disabled": "No",
        "contact_role_bill_to": "Yes",
        "contact_role_employer": "No",
        "contact_role_referrer": "No",
        "contact_role_bill_to_cc": "No",
        "name": "xxxx xxx, Ms"
    },
    {
        "contact_id": "5", // internal iinsight ID
        "company_name": "xxxxx",
        "job_title": "xxx",
        "position": "Human Resources Manager",
        "phone1": "(##) #### ####",
        "mobile": "",
        "email": "xxxx@xxx.xx",
        "address": "xxx xxxxx xxxxx",
        "suburb": "xxxx",
        "state": "xxxx",
        "postcode": "xxxx",
        "date_created": "##-##-####",
        "date_disabled": "##-##-####",
        "disabled": "No",
        "contact_role_bill_to": "Yes",
        "contact_role_employer": "No",
        "contact_role_referrer": "No",
        "contact_role_bill_to_cc": "No",
        "name": "xxxx xxx"
    },
]

4. List Case Contacts Details (api1/contacts/details)

This method will answer with a case contact details (case oriented data) that belong to a case. It will be in JSON format.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/details GET
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/details GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
case_id Case ID. (i.e.: 1) Yes
contact_id Contact ID. (i.e.: 1) Yes
Response

    {
        "company_id": 1,
        "company_name": "xxxxx",
        "title": "xx",
        "first_name": "xxx",
        "last_name": "xxxx",
        "position": "xxxx",
        "job_title": "xxx",
        "department": "xxxx",
        "provider_no": "###",
        "biller_id": "123456",
        "street": "## xxx xxx",
        "postcode": "###",
        "suburb": "xxx",
        "sublocality": "xxxx",
        "state": "xxxx",
        "country": "xxxx",
        "latitude": "###.####",
        "longitude": "###.###",
        "email": "xxxx@xxx.xx",
        "phone1": "####",
        "phone2": "####",
        "fax": "####",
        "mobile": "####",
        "notes": "xxxxxx",
        "date_created": "##-##-####",
        "date_disabled": "##-##-####",
        "disabled": "Yes/No",
        "contact_role_bill_to": "Yes/No",
        "contact_role_employer": "Yes/No",
        "contact_role_referrer": "Yes/No",
        "contact_role_bill_to_cc": "Yes/No"
    }

5. Associate Contact to Case (api1/contacts/associate_to_case)

This method will allow to associate a contact with a case in iinsight.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/associate_to_case POST
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/associate_to_case POST
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
contact_id Contact ID (i.e.: 1). Leave null to create a new contact. No
case_id Case ID. (i.e.: 1) Yes
company_id Company ID. (i.e.: 1) Yes, if contact_id is provided
created_on Associeded Date. (i.e.: ##-##-####) Yes
disabled Contact disabled for that case. Options Yes/No Yes
disabled_on Contact disabled date for that case. (i.e.: ##-##-####) Yes if disabled is Yes
bill_to_cc Contact bill cc to case. Options Yes/No Yes
bill_to Contact bill to case. Options Yes/No Yes
employer Contact employer for that case. Options Yes/No Yes
referrer Contact referrer for that case. Options Yes/No Yes
notes Contact's notes No
company_name Company's name Yes
first_name Contact's first name Yes
last_name Contact's last name Yes
title Contact's title No
position Contact's position No
department Contact's department No
phone1 Contact's phone1 No
phone2 Contact's phone2 No
fax Contact's fax No
mobile Contact's mobile No
email Contact's email (i.e.: xxx@xxx.xx) No
street Contact's street adress No
state Contact's state No
postcode Contact's postcode No
suburb Contact's suburb No
country Contact's country No
latitude Contact's latitude No
longitude Contact's longitude No
provider_no Contact's provider_no No
biller_id Contact's biller_id No
job_title Contact's job_title No
custom_fields An array of Custom fields in JSON format. (i.e.: [{"field":"custom_field_details.text_1_01","value":"test"}, {"field":"custom_field_details.text_1_02","value":"test2"}]) No
proceed_registration_anyway Bypass duplicate check confirmation. Options: Yes/No No
Possible Responses
Query Params
Status Code Scenario Response Example
400 Bad Request Validation Error 
{
  "status": false,
  "errors": {
    "case_id": "The case_id field is required",
    "email": "Invalid email format"
  }
}
200 OK (Confirmation Required) Duplicate Contact Detected 
{
  "status": false,
  "confirm": "proceed_registration_anyway",
  "message": "There are 3 existing contacts that might have the same Name, Phone1. Do you want to review them?",
  "data": [
    {
      "record_id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "phone1": "555-1234"
    },
    {
      "record_id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "phone1": "555-5678"
    }
  ]
}
200 OK Success (New Contact Created) 
{
  "response": "Contact Associated",
  "case_contact_id": 14120,
  "contact_id": "433",
  "company_id": "19"
}
Parameter Value Mandatory
company_id Company's ID No
company_name Company's name Yes
first_name Contact's first name No
last_name Contact's last name Yes
title Contact's title No
position Contact's position No
department Contact's department No
created_on Creation date Yes
phone1 Contact's phone1 Yes
phone2 Contact's phone2 No
fax Contact's fax No
mobile Contact's mobile No
email Contact's email (i.e.: xxx@xxx.xx) No
street Contact's street address No
state Contact's state address No
postcode Contact's postcode address No
suburb Contact's suburb address No
sublocality Contact's sublocality address No
country Contact's country address No
latitude Contact's latitude address No
longitude Contact's longitude address No
care_of Contact's care of address No
mmm_classification Contact's mmm classification address No
provider_no Contact's provider_no No
biller_id Contact's biller_id No
Response
500 Internal Error Server/Database Error 
{
  "status": false,
  "error": "Internal server error",
  "message": "Database connection failed"
}
Important Response Notes:

6. New contact (api1/contacts/new)

This method will allow to create a Contact.
If no company ID is given, it will look for a company with the given company name else it will create also a company.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/new POST
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/new POST
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
company_id Company's ID No
company_name Company's name Yes
first_name Contact's first name No
last_name Contact's last name Yes
title Contact's title No
position Contact's position No
department Contact's department No
phone1 Contact's phone1 No
phone2 Contact's phone2 No
fax Contact's fax No
mobile Contact's mobile No
email Contact's email (i.e.: xxx@xxx.xx) No
street Contact's street address No
state Contact's state address No
postcode Contact's postcode address No
suburb Contact's suburb address No
sublocality Contact's sublocality address No
country Contact's country address No
latitude Contact's latitude address No
longitude Contact's longitude address No
care_of Contact's care of address No
mmm_classification Contact's mmm classification address No
provider_no Contact's provider_no No
biller_id Contact's biller_id No
Response
{
    "response": "Contact created",
    "id": 312,
    "company_id": "324"
}

7. Check Case Contact Deletion Info (api1/contacts/check_delete_from_case)

This method will answer with deletion info regarding a case contact in JSON format.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/check_delete_from_case GET
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/check_delete_from_case GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
contact_id A contact id. (i.e.: 123) Yes
case_id A case id. (i.e.: 1) Yes
Response
{
  "bill_to": true, // The case contact is the bill to
  "referrer": false, // The case contact is the referrer
  "employer": false, // The case contact is the employer
  "invoices": 1, // Invoices linked to case contact (for specific case)
  "delete": false, // can be deleted
  "disable": true, // can be disabled
  "transfer_invoices": false, // a flag to know if transfer invoices is required
}

8. Disable Case Contact (api1/contacts/disable_from_case)

This method will allow to disable a Case Contact.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/disable_from_case POST
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/disable_from_case POST
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
contact_id A contact id. (i.e.: 123) Yes
case_id A case id. (i.e.: 1) Yes
Response
{
  "success": true,
  "message": "Case Contact disabled"
}

9. Delete Case Contact (api1/contacts/delete_from_case)

This method will allow to delete a Case Contact.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/delete_from_case POST
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/delete_from_case POST
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
contact_id A contact id. (i.e.: 123) Yes
case_id A case id. (i.e.: 1) Yes
Response
{
  "success": true,
  "message": "Case Contact deleted"
}

10. Get Contacts for Transfer Invoices (api1/contacts/contacts_for_transfer_invoices)

This method will answer with a list of alternative contacts to be selected to transfer invoices in JSON format.

URL
Server URL HTTP type
UAT https://api-usa-uat.iinsightonline.com/api1/contacts/contacts_for_transfer_invoices GET
PRODUCTION https://api-usa.iinsightonline.com/api1/contacts/contacts_for_transfer_invoices GET
Authorization
Parameter Value Mandatory
Type Bearer Token Yes
Token The token is generated using the /auth/login method Yes
Query Params
Parameter Value Mandatory
contact_id A contact id. (i.e.: 123) Yes
Response
[
  {
    "contact_id": "336",
    "first_name": "Test",
    "last_name": "Test"
  },
  {
    "contact_id": "433",
    "first_name": "Tyrion",
    "last_name": "Lannister"
  },
]